mlos_core.optimizers package

Basic initializer module for the mlos_core optimizers.

class mlos_core.optimizers.BaseOptimizer(*, parameter_space: ConfigurationSpace, optimization_targets: List[str], objective_weights: List[float] | None = None, space_adapter: BaseSpaceAdapter | None = None)

Bases: object

Optimizer abstract base class defining the basic interface.

Attributes:

space_adapter

Get the space adapter instance (if any).

Methods

cleanup()	Remove temp files, release resources, etc.
get_best_observations(*[, n_max])	Get the N best observations so far as a triplet of DataFrames (config, score, context).
get_observations()	Returns the observations as a triplet of DataFrames (config, score, context).
register(*, configs, scores[, context, metadata])	Wrapper method, which employs the space adapter (if any), before registering the configs and scores.
register_pending(*, configs[, context, metadata])	Registers the given configs as "pending".
suggest(*[, context, defaults])	Wrapper method, which employs the space adapter (if any), after suggesting a new configuration.

cleanup() → None

Remove temp files, release resources, etc.

after use. Default is no-op. Redefine this method in optimizers that require cleanup.

get_best_observations(*, n_max: int = 1) → Tuple[DataFrame, DataFrame, DataFrame | None]

Get the N best observations so far as a triplet of DataFrames (config, score, context). Default is N=1. The columns are ordered in ASCENDING order of the optimization targets. The function uses pandas.DataFrame.nsmallest(…, keep=”first”) method under the hood.

Parameters:

n_maxint

Maximum number of best observations to return. Default is 1.

Returns:

observationsTuple[pd.DataFrame, pd.DataFrame, Optional[pd.DataFrame]]

A triplet of best (config, score, context) DataFrames of best observations.

get_observations() → Tuple[DataFrame, DataFrame, DataFrame | None]

Returns the observations as a triplet of DataFrames (config, score, context).

Returns:

observationsTuple[pd.DataFrame, pd.DataFrame, Optional[pd.DataFrame]]

A triplet of (config, score, context) DataFrames of observations.

register(*, configs: DataFrame, scores: DataFrame, context: DataFrame | None = None, metadata: DataFrame | None = None) → None

Wrapper method, which employs the space adapter (if any), before registering the configs and scores.

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

scorespd.DataFrame

Scores from running the configs. The index is the same as the index of the configs.

contextpd.DataFrame

Not Yet Implemented.

metadataOptional[pd.DataFrame]

Metadata returned by the backend optimizer’s suggest method.

abstract register_pending(*, configs: DataFrame, context: DataFrame | None = None, metadata: DataFrame | None = None) → None

Registers the given configs as “pending”. That is it say, it has been suggested by the optimizer, and an experiment trial has been started. This can be useful for executing multiple trials in parallel, retry logic, etc.

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

contextpd.DataFrame

Not Yet Implemented.

metadataOptional[pd.DataFrame]

Metadata returned by the backend optimizer’s suggest method.

property space_adapter: BaseSpaceAdapter | None

Get the space adapter instance (if any).

suggest(*, context: DataFrame | None = None, defaults: bool = False) → Tuple[DataFrame, DataFrame | None]

Wrapper method, which employs the space adapter (if any), after suggesting a new configuration.

Parameters:

contextpd.DataFrame

Not Yet Implemented.

defaultsbool

Whether or not to return the default config instead of an optimizer guided one. By default, use the one from the optimizer.

Returns:

configurationpd.DataFrame

Pandas dataframe with a single row. Column names are the parameter names.

metadataOptional[pd.DataFrame]

The metadata associated with the given configuration used for evaluations. Backend optimizer specific.

class mlos_core.optimizers.FlamlOptimizer(*, parameter_space: ConfigurationSpace, optimization_targets: List[str], objective_weights: List[float] | None = None, space_adapter: BaseSpaceAdapter | None = None, low_cost_partial_config: dict | None = None, seed: int | None = None)

Bases: BaseOptimizer

Wrapper class for FLAML Optimizer: A fast library for AutoML and tuning.

Attributes:

space_adapter

Get the space adapter instance (if any).

Methods

cleanup()	Remove temp files, release resources, etc.
get_best_observations(*[, n_max])	Get the N best observations so far as a triplet of DataFrames (config, score, context).
get_observations()	Returns the observations as a triplet of DataFrames (config, score, context).
register(*, configs, scores[, context, metadata])	Wrapper method, which employs the space adapter (if any), before registering the configs and scores.
register_pending(*, configs[, context, metadata])	Registers the given configs as "pending".
suggest(*[, context, defaults])	Wrapper method, which employs the space adapter (if any), after suggesting a new configuration.

register_pending(*, configs: DataFrame, context: DataFrame | None = None, metadata: DataFrame | None = None) → None

Registers the given configs as “pending”. That is it say, it has been suggested by the optimizer, and an experiment trial has been started. This can be useful for executing multiple trials in parallel, retry logic, etc.

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

contextpd.DataFrame

Not Yet Implemented.

metadataOptional[pd.DataFrame]

Metadata returned by the backend optimizer’s suggest method.

class mlos_core.optimizers.OptimizerFactory

Bases: object

Simple factory class for creating BaseOptimizer-derived objects.

Methods

create(*, parameter_space, optimization_targets)

Create a new optimizer instance, given the parameter space, optimizer type, and potential optimizer options.

static create(*, parameter_space: ConfigurationSpace, optimization_targets: List[str], optimizer_type: OptimizerType = OptimizerType.FLAML, optimizer_kwargs: dict | None = None, space_adapter_type: SpaceAdapterType = SpaceAdapterType.IDENTITY, space_adapter_kwargs: dict | None = None) → ConcreteOptimizer

Create a new optimizer instance, given the parameter space, optimizer type, and potential optimizer options.

Parameters:

parameter_spaceConfigSpace.ConfigurationSpace

Input configuration space.

optimization_targetsList[str]

The names of the optimization targets to minimize.

optimizer_typeOptimizerType

Optimizer class as defined by Enum.

optimizer_kwargsOptional[dict]

Optional arguments passed in Optimizer class constructor.

space_adapter_typeOptional[SpaceAdapterType]

Space adapter class to be used alongside the optimizer.

space_adapter_kwargsOptional[dict]

Optional arguments passed in SpaceAdapter class constructor.

Returns:

optimizerConcreteOptimizer

Instance of concrete optimizer class (e.g., RandomOptimizer, FlamlOptimizer, SmacOptimizer, etc.).

class mlos_core.optimizers.RandomOptimizer(*, parameter_space: ConfigurationSpace, optimization_targets: List[str], objective_weights: List[float] | None = None, space_adapter: BaseSpaceAdapter | None = None)

Bases: BaseOptimizer

Optimizer class that produces random suggestions. Useful for baseline comparison against Bayesian optimizers.

Parameters:

parameter_spaceConfigSpace.ConfigurationSpace

The parameter space to optimize.

Attributes:

space_adapter

Get the space adapter instance (if any).

Methods

cleanup()	Remove temp files, release resources, etc.
get_best_observations(*[, n_max])	Get the N best observations so far as a triplet of DataFrames (config, score, context).
get_observations()	Returns the observations as a triplet of DataFrames (config, score, context).
register(*, configs, scores[, context, metadata])	Wrapper method, which employs the space adapter (if any), before registering the configs and scores.
register_pending(*, configs[, context, metadata])	Registers the given configs as "pending".
suggest(*[, context, defaults])	Wrapper method, which employs the space adapter (if any), after suggesting a new configuration.

register_pending(*, configs: DataFrame, context: DataFrame | None = None, metadata: DataFrame | None = None) → None

Registers the given configs as “pending”. That is it say, it has been suggested by the optimizer, and an experiment trial has been started. This can be useful for executing multiple trials in parallel, retry logic, etc.

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

contextpd.DataFrame

Not Yet Implemented.

metadataOptional[pd.DataFrame]

Metadata returned by the backend optimizer’s suggest method.

class mlos_core.optimizers.SmacOptimizer(*, parameter_space: ConfigurationSpace, optimization_targets: List[str], objective_weights: List[float] | None = None, space_adapter: BaseSpaceAdapter | None = None, seed: int | None = 0, run_name: str | None = None, output_directory: str | None = None, max_trials: int = 100, n_random_init: int | None = None, max_ratio: float | None = None, use_default_config: bool = False, n_random_probability: float = 0.1)

Bases: BaseBayesianOptimizer

Wrapper class for SMAC based Bayesian optimization.

Attributes:

n_random_init

Gets the number of random samples to use to initialize the optimizer’s search space sampling.

space_adapter

Get the space adapter instance (if any).

Methods

acquisition_function(*, configs[, context])	Invokes the acquisition function from this Bayesian optimizer for the given configuration.
cleanup()	Remove temp files, release resources, etc.
get_best_observations(*[, n_max])	Get the N best observations so far as a triplet of DataFrames (config, score, context).
get_observations()	Returns the observations as a triplet of DataFrames (config, score, context).
register(*, configs, scores[, context, metadata])	Wrapper method, which employs the space adapter (if any), before registering the configs and scores.
register_pending(*, configs[, context, metadata])	Registers the given configs as "pending".
suggest(*[, context, defaults])	Wrapper method, which employs the space adapter (if any), after suggesting a new configuration.
surrogate_predict(*, configs[, context])	Obtain a prediction from this Bayesian optimizer's surrogate model for the given configuration(s).

acquisition_function(*, configs: DataFrame, context: DataFrame | None = None) → ndarray[Any, dtype[_ScalarType_co]]

Invokes the acquisition function from this Bayesian optimizer for the given configuration.

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

contextpd.DataFrame

Not Yet Implemented.

cleanup() → None

Remove temp files, release resources, etc.

after use. Default is no-op. Redefine this method in optimizers that require cleanup.

property n_random_init: int

Gets the number of random samples to use to initialize the optimizer’s search space sampling.

Note: This may not be equal to the value passed to the initializer, due to logic present in the SMAC. See Also: max_ratio

Returns:

int

The number of random samples used to initialize the optimizer’s search space sampling.

register_pending(*, configs: DataFrame, context: DataFrame | None = None, metadata: DataFrame | None = None) → None

Registers the given configs as “pending”. That is it say, it has been suggested by the optimizer, and an experiment trial has been started. This can be useful for executing multiple trials in parallel, retry logic, etc.

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

contextpd.DataFrame

Not Yet Implemented.

metadataOptional[pd.DataFrame]

Metadata returned by the backend optimizer’s suggest method.

surrogate_predict(*, configs: DataFrame, context: DataFrame | None = None) → ndarray[Any, dtype[_ScalarType_co]]

Obtain a prediction from this Bayesian optimizer’s surrogate model for the given configuration(s).

Parameters:

configspd.DataFrame

Dataframe of configs / parameters. The columns are parameter names and the rows are the configs.

contextpd.DataFrame

Not Yet Implemented.

class mlos_core.optimizers.SpaceAdapterType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumerate supported MlosCore space adapters.

IDENTITY = <class 'mlos_core.spaces.adapters.identity_adapter.IdentityAdapter'>

A no-op adapter will be used.

LLAMATUNE = <class 'mlos_core.spaces.adapters.llamatune.LlamaTuneAdapter'>

An instance of LlamaTuneAdapter class will be used.

Subpackages

• mlos_core.optimizers.bayesian_optimizers package
  • BaseBayesianOptimizer
    • BaseBayesianOptimizer.acquisition_function()
    • BaseBayesianOptimizer.surrogate_predict()
  • SmacOptimizer
    • SmacOptimizer.acquisition_function()
    • SmacOptimizer.cleanup()
    • SmacOptimizer.n_random_init
    • SmacOptimizer.register_pending()
    • SmacOptimizer.surrogate_predict()
  • Submodules
    • mlos_core.optimizers.bayesian_optimizers.bayesian_optimizer module
      • BaseBayesianOptimizer
    • mlos_core.optimizers.bayesian_optimizers.smac_optimizer module
      • SmacOptimizer

Submodules

• mlos_core.optimizers.flaml_optimizer module
  • EvaluatedSample
    • EvaluatedSample.config
    • EvaluatedSample.score
  • FlamlOptimizer
    • FlamlOptimizer.register_pending()
• mlos_core.optimizers.optimizer module
  • BaseOptimizer
    • BaseOptimizer.cleanup()
    • BaseOptimizer.get_best_observations()
    • BaseOptimizer.get_observations()
    • BaseOptimizer.register()
    • BaseOptimizer.register_pending()
    • BaseOptimizer.space_adapter
    • BaseOptimizer.suggest()
• mlos_core.optimizers.random_optimizer module
  • RandomOptimizer
    • RandomOptimizer.register_pending()