Optimization

class ambr.optimization.MultiObjectiveSMAC(model_type: Type[Model], param_space: SMACParameterSpace, objectives: Dict[str, Callable[[Model], float]], n_trials: int = 100, n_workers: int = 1, seed: int | None = None, strategy: str = 'pareto', use_multi_fidelity: bool = False)[source]

Bases: object

Multi-objective parameter optimization using SMAC.

optimize() → Dict[str, Any][source]

Run the multi-objective optimization.

Returns:

Dictionary containing Pareto-optimal configurations and results

class ambr.optimization.ParameterSpace(parameters: Dict[str, Any])[source]

Bases: object

Define the parameter space for optimization.

grid_sample() → List[Dict[str, Any]][source]

Generate all parameter combinations in a grid.

Returns:

List of parameter dictionaries

sample() → Dict[str, Any][source]

Sample a random parameter combination.

Returns:

Dictionary with parameter values

class ambr.optimization.SMACOptimizer(model_type: Type[Model], param_space: SMACParameterSpace, objective: Callable[[Model], float], n_trials: int = 100, n_workers: int = 1, seed: int | None = None, strategy: str = 'bayesian', acquisition_function: str = 'ei', initial_design: str = 'latin_hypercube', surrogate_model: str = 'random_forest', use_multi_fidelity: bool = False, use_random_search: bool = False)[source]

Bases: object

Optimize model parameters using SMAC with various strategies.

optimize() → Dict[str, Any][source]

Run the optimization.

Returns:

Dictionary containing best configuration and results

class ambr.optimization.SMACParameterSpace[source]

Bases: object

Define the parameter space for SMAC optimization.

add_parameter(name: str, param_type: str, bounds: tuple | None = None, choices: List[Any] | None = None, default: Any = None, is_fidelity: bool = False)[source]

Add a parameter to the space.

Parameters:

  • name – Parameter name

  • param_type – Type of parameter (‘float’, ‘int’, ‘categorical’)

  • bounds – Tuple of (min, max) for numeric parameters

  • choices – List of possible values for categorical parameters

  • default – Default value

  • is_fidelity – Whether this is a fidelity parameter

get_configspace()[source]

Get the SMAC configuration space.

ambr.optimization.bayesian_optimization(model_class: Type[Model], parameter_space: ParameterSpace, metric: str, n_calls: int = 10, iterations: int = 1, minimize: bool = False, random_state: int | None = None, n_initial_design: int = 5) → List[Dict[str, Any]][source]

Perform Bayesian optimisation using SMAC3’s Gaussian Process facade.

Converts the simple ParameterSpace to a SMAC3 ConfigurationSpace internally and runs true Bayesian optimisation with Expected Improvement acquisition. Requires SMAC3 to be installed (pip install smac).

Parameters:

  • model_class – Model class to optimize.

  • parameter_space – Parameter space to search.

  • metric – Metric to optimize.

  • n_calls – Total number of function evaluations.

  • iterations – Number of iterations per parameter combination.

  • minimize – Whether to minimize (True) or maximize (False).

  • random_state – Random state for reproducibility.

  • n_initial_design – Number of initial random designs before Bayesian search begins.

Returns:

List of results sorted by objective value (best first).

Perform grid search optimization.

Parameters:

  • model_class – Model class to optimize

  • parameter_space – Parameter space to search

  • metric – Metric to optimize

  • iterations – Number of iterations per parameter combination

  • minimize – Whether to minimize the metric

Returns:

List of results sorted by objective value (best first)

ambr.optimization.objective_function(model_class: Type[Model], parameters: Dict[str, Any], metric: str, iterations: int = 1, minimize: bool = False) → float[source]

Evaluate objective function for a model with given parameters.

Parameters:

  • model_class – Model class to instantiate

  • parameters – Parameters to pass to model

  • metric – Name of metric to optimize

  • iterations – Number of iterations to average over

  • minimize – Whether to minimize (True) or maximize (False)

Returns:

Objective value

Perform random search optimization.

Parameters:

  • model_class – Model class to optimize

  • parameter_space – Parameter space to search

  • metric – Metric to optimize

  • n_samples – Number of random samples to evaluate

  • iterations – Number of iterations per parameter combination

  • minimize – Whether to minimize the metric

  • seed – Random seed for reproducibility

Returns:

List of results sorted by objective value (best first)

The optimization module provides tools for parameter tuning and model optimization.

Parameter Space

class ambr.ParameterSpace(parameters: Dict[str, Any])[source]

Bases: object

Define the parameter space for optimization.

grid_sample() → List[Dict[str, Any]][source]

Generate all parameter combinations in a grid.

Returns:

List of parameter dictionaries

sample() → Dict[str, Any][source]

Sample a random parameter combination.

Returns:

Dictionary with parameter values

Define parameter ranges for optimization:

from ambr import ParameterSpace, IntRange

space = ParameterSpace({
    'n_agents': IntRange(50, 200),
    'learning_rate': [0.01, 0.1, 0.5],
    'strategy': ['random', 'greedy', 'smart']
})

Optimization Functions

Bayesian Optimization

ambr.bayesian_optimization(model_class: Type[Model], parameter_space: ParameterSpace, metric: str, n_calls: int = 10, iterations: int = 1, minimize: bool = False, random_state: int | None = None, n_initial_design: int = 5) → List[Dict[str, Any]][source]

Perform Bayesian optimisation using SMAC3’s Gaussian Process facade.

Converts the simple ParameterSpace to a SMAC3 ConfigurationSpace internally and runs true Bayesian optimisation with Expected Improvement acquisition. Requires SMAC3 to be installed (pip install smac).

Parameters:

  • model_class – Model class to optimize.

  • parameter_space – Parameter space to search.

  • metric – Metric to optimize.

  • n_calls – Total number of function evaluations.

  • iterations – Number of iterations per parameter combination.

  • minimize – Whether to minimize (True) or maximize (False).

  • random_state – Random state for reproducibility.

  • n_initial_design – Number of initial random designs before Bayesian search begins.

Returns:

List of results sorted by objective value (best first).

Intelligent parameter search using Bayesian optimization:

best_params, best_score = am.bayesian_optimization(
    model_class=MyModel,
    param_space=space,
    metric='efficiency',
    minimize=False,
    n_calls=30,
    n_runs=5
)