smac.facade.abstract_facade

Classes

AbstractFacade(scenario, target_function, *)

Facade is an abstraction on top of the SMBO backend to organize the components of a Bayesian Optimization loop in a configurable and separable manner to suit the various needs of different (hyperparameter) optimization pipelines.

Interfaces

class smac.facade.abstract_facade.AbstractFacade(scenario, target_function, *, model=None, acquisition_function=None, acquisition_maximizer=None, initial_design=None, random_design=None, intensifier=None, multi_objective_algorithm=None, runhistory_encoder=None, logging_level=None, callbacks=[], overwrite=False)[source]

Bases: object

Facade is an abstraction on top of the SMBO backend to organize the components of a Bayesian Optimization loop in a configurable and separable manner to suit the various needs of different (hyperparameter) optimization pipelines.

With the exception to scenario and target_function, which are expected of the user, the parameters model, acquisition_function, acquisition_maximizer, initial_design, random_design, intensifier, multi_objective_algorithm, runhistory_encoder can either be explicitly specified in the subclasses’ get_* methods (defining a specific BO pipeline) or be instantiated by the user to overwrite a pipelines components explicitly.

Parameters:

  • scenario (Scenario) – The scenario object, holding all environmental information.

  • target_function (Callable | str | AbstractRunner) – This function is called internally to judge a trial’s performance. If a string is passed, it is assumed to be a script. In this case, TargetFunctionScriptRunner is used to run the script.

  • model (AbstractModel | None, defaults to None) – The surrogate model.

  • acquisition_function (AbstractAcquisitionFunction | None, defaults to None) – The acquisition function.

  • acquisition_maximizer (AbstractAcquisitionMaximizer | None, defaults to None) – The acquisition maximizer, deciding which configuration is most promising based on the surrogate model and acquisition function.

  • initial_design (InitialDesign | None, defaults to None) – The sampled configurations from the initial design are evaluated before the Bayesian optimization loop starts.

  • random_design (RandomDesign | None, defaults to None) – The random design is used in the acquisition maximier, deciding whether the next configuration should be drawn from the acquisition function or randomly.

  • intensifier (AbstractIntensifier | None, defaults to None) – The intensifier decides which trial (combination of configuration, seed, budget and instance) should be run next.

  • multi_objective_algorithm (AbstractMultiObjectiveAlgorithm | None, defaults to None) – In case of multiple objectives, the objectives need to be interpreted so that an optimization is possible. The multi objective algorithm takes care of that.

  • runhistory_encoder (RunHistoryEncoder | None, defaults to None) – Based on the runhistory, the surrogate model is trained. However, the data first needs to be encoded, which is done by the runhistory encoder. For example, inactive hyperparameters need to be encoded or cost values can be log transformed.

  • logging_level (int | Path | None) – The level of logging (the lowest level 0 indicates the debug level). If a path is passed, a yaml file is expected with the logging configuration. If nothing is passed, the default logging.yml from SMAC is used.

  • callbacks (list[Callback], defaults to []) – Callbacks, which are incorporated into the optimization loop.

  • overwrite (bool, defaults to False) – When True, overwrites the run results if a previous run is found that is inconsistent in the meta data with the current setup. If overwrite is set to False, the user is asked for the exact behaviour (overwrite completely, save old run, or use old results).

ask()[source]

Asks the intensifier for the next trial. This method returns only trials with the intend to run.

Return type:

TrialInfo

abstract static get_acquisition_function(scenario)[source]

Returns the acquisition function instance used in the BO loop, defining the exploration/exploitation trade-off.

Return type:

AbstractAcquisitionFunction

abstract static get_acquisition_maximizer(scenario)[source]

Returns the acquisition optimizer instance to be used in the BO loop, specifying how the acquisition function instance is optimized.

Return type:

AbstractAcquisitionMaximizer

abstract static get_initial_design(scenario)[source]

Returns an instance of the initial design class to be used in the BO loop, specifying how the configurations the BO loop is ‘warm-started’ with are selected.

Return type:

AbstractInitialDesign

abstract static get_intensifier(scenario)[source]

Returns the intensifier instance to be used in the BO loop, specifying how to challenge the incumbent configuration on other problem instances.

Return type:

AbstractIntensifier

abstract static get_model(scenario)[source]

Returns the surrogate cost model instance used in the BO loop.

Return type:

AbstractModel

abstract static get_multi_objective_algorithm(scenario)[source]

Returns the multi-objective algorithm instance to be used in the Bayesian optimization loop, specifying the scalarization strategy for multiple objectives’ costs

Return type:

AbstractMultiObjectiveAlgorithm

get_next_configurations()[source]

Choose next candidate solution with Bayesian optimization. The suggested configurations depend on the surrogate model acquisition optimizer/function. This method is used by the intensifier.

Return type:

Iterator[Configuration]

abstract static get_random_design(scenario)[source]

Returns an instance of the random design class to be used in the BO loop, specifying how to interleave the BO iterations with randomly selected configurations.

Return type:

AbstractRandomDesign

abstract static get_runhistory_encoder(scenario)[source]

Returns an instance of the runhistory encoder class to be used in the Bayesian optimization loop, specifying how the runhistory is to be prepared for the next surrogate model.

Return type:

AbstractRunHistoryEncoder

get_target_function_budgets()[source]

Which budgets are used to call the target function.

Return type:

list[Optional[float]]

get_target_function_instances()[source]

Which instances are used to call the target function.

Return type:

list[Optional[str]]

get_target_function_seeds()[source]

Which seeds are used to call the target function.

Return type:

list[int]

property incumbent: ConfigSpace.configuration_space.Configuration | None

The best configuration so far.

Return type:

Optional[Configuration]

property meta: dict[str, Any]

Generates a hash based on all components of the facade. This is used for the run name or to determine whether a run should be continued or not.

Return type:

dict[str, Any]

optimize()[source]

Optimizes the algorithm.

Returns:

incumbent – Best found configuration.

Return type:

Configuration

property runhistory: RunHistory

The run history, which is filled with all information during the optimization process.

Return type:

RunHistory

property scenario: Scenario

The scenario object.

Return type:

Scenario

property stats: Stats

The stats object, which is updated during the optimization and shows relevant information, e.g., how many trials have been finished and how the trajectory looks like.

Return type:

Stats

tell(info, value, save=True)[source]

Adds the result of a trial to the runhistory and updates the intensifier. Also, the stats object is updated.

Parameters:

  • info (TrialInfo) – Describes the trial from which to process the results.

  • value (TrialValue) – Contains relevant information regarding the execution of a trial.

  • save (bool, optional to True) – Whether the runhistory should be saved.

Return type:

None

validate(config, *, instances=None, seed=None)[source]

Validates a configuration with different seeds than in the optimization process and on the highest budget (if budget type is real-valued).

Parameters:

  • config (Configuration) – Configuration to validate

  • instances (list[str] | None, defaults to None) – Which instances to validate. If None, all instances specified in the scenario are used. In case that the budget type is real-valued budget, this argument is ignored.

  • seed (int | None, defaults to None) – If None, the seed from the scenario is used.

Returns:

cost – The averaged cost of the configuration. In case of multi-fidelity, the cost of each objective is averaged.

Return type:

float | list[float]

previous

smac.facade

next

smac.facade.algorithm_configuration_facade