optimpv.axBOtorch package

Submodules

optimpv.axBOtorch.EGBO module

class optimpv.axBOtorch.EGBO.EGBOAcquisition(surrogate: Surrogate, search_space_digest: SearchSpaceDigest, torch_opt_config: TorchOptConfig, botorch_acqf_class: type[AcquisitionFunction], botorch_acqf_options: dict[str, Any], botorch_acqf_classes_with_options: list[tuple[type[AcquisitionFunction], dict[str, Any]]] | None = None, n: int | None = None, options: dict[str, Any] | None = None, pop_size: int = 256, EA_algo: str = 'UNSGA3')

Bases: Acquisition

Implement the acquisition function of Evolution-Guided Bayesian Optimization (EGBO).

Based on the following paper: Low, A.K.Y., Mekki-Berrada, F., Gupta, A. et al. Evolution-guided Bayesian optimization for constrained multi-objective optimization in self-driving labs. npj Comput Mater 10, 104 (2024). https://doi.org/10.1038/s41524-024-01274-x

Code inspired the repository: https://github.com/andrelowky/CMOO-Algorithm-Development/

optimize(n: int, search_space_digest: SearchSpaceDigest, inequality_constraints: list[tuple[Tensor, Tensor, float]] | None = None, fixed_features: dict[int, float] | None = None, rounding_func: Callable[[Tensor], Tensor] | None = None, optimizer_options: dict[str, Any] | None = None) → tuple[Tensor, Tensor, Tensor]

Generate a set of candidates via multi-start optimization. Obtains candidates and their associated acquisition function values.

Parameters:

• n – The number of candidates to generate.

• search_space_digest – A SearchSpaceDigest object containing search space properties, e.g. bounds for optimization.

• inequality_constraints – A list of tuples (indices, coefficients, rhs), with each tuple encoding an inequality constraint of the form sum_i (X[indices[i]] * coefficients[i]) >= rhs.

• fixed_features – A map {feature_index: value} for features that should be fixed to a particular value during generation.

• rounding_func – A function that post-processes an optimization result appropriately (i.e., according to round-trip transformations).

• optimizer_options – Options for the optimizer function, e.g. sequential or raw_samples.

Returns:

A three-element tuple containing an n x d-dim tensor of generated candidates, a tensor with the associated acquisition values, and a tensor with the weight for each candidate.

optimpv.axBOtorch.axBOtorchOptimizer module

axBOtorchOptimizer module. This module contains the axBOtorchOptimizer class. The class is used to run the bayesian optimization process using the Ax library.

class optimpv.axBOtorch.axBOtorchOptimizer.TurboState(dim, batch_size, best_value, **kwargs)

Bases: object

batch_size: int

best_value: float = -inf

dim: int

failure_counter: int = 0

failure_tolerance: int = nan

length: float = 0.8

length_max: float = 1.6

length_min: float = 0.0078125

restart_triggered: bool = False

success_counter: int = 0

success_tolerance: int = 3

class optimpv.axBOtorch.axBOtorchOptimizer.axBOtorchOptimizer(params=None, agents=None, models=['SOBOL', 'BOTORCH_MODULAR'], n_batches=[1, 10], batch_size=[10, 2], ax_client=None, max_parallelism=-1, model_kwargs_list=None, model_gen_kwargs_list=None, existing_data=None, suggest_only=False, name='ax_opti', **kwargs)

Bases: BaseAgent

Initialize the axBOtorchOptimizer class. The class is used to run the optimization process using the Ax library.

Parameters:

• params (list of Fitparam() objects, optional) – List of Fitparam() objects, by default None

• agents (list of Agent() objects, optional) – List of Agent() objects see optimpv/general/BaseAgent.py for a base class definition, by default None

• models (list, optional) – list of models to use for the optimization process, by default [‘SOBOL’,’BOTORCH_MODULAR’]

• n_batches (list, optional) – list of the number of batches for each model, by default [1,10]

• batch_size (list, optional) – list of the batch sizes for each model, by default [10,2]

• ax_client (AxClient, optional) – AxClient object, by default None

• max_parallelism (int, optional) – maximum number of parallel processes to run, by default 10

• model_kwargs_list (dict, optional) – dictionary of model kwargs for each model, by default None

• model_gen_kwargs_list (dict, optional) – dictionary of model generation kwargs for each model, by default None

• existing_data (DataFrame, optional) – existing data to use for the optimization process, by default None

• suggest_only (bool, optional) – if True, the optimization process will only suggest new points without running the agents, by default False

• name (str, optional) – name of the optimization process, by default ‘ax_opti’

Raises:

• ValueError – raised if the number of batches and the number of models are not the same

• ValueError – raised if the model is not a string or a Models enum

• ValueError – raised if the model_kwargs_list and models do not have the same length

• ValueError – raised if the model_gen_kwargs_list and models do not have the same length

attach_existing_data()

Attach existing data to the Ax client

create_generation_strategy()

Create a generation strategy for the optimization process using the models and the number of batches and batch sizes. See ax documentation for more details: https://ax.dev/tutorials/generation_strategy.html

Returns:

The generation strategy for the optimization process

Return type:

GenerationStrategy

Raises:

ValueError – If the model is not a string or a Models enum

create_objectives()

Create the objectives for the optimization process. The objectives are the metrics of the agents. The objectives are created using the metric, minimize and threshold attributes of the agents. If the agent has an exp_format attribute, it is used to create the objectives.

Returns:

A dictionary of the objectives for the optimization process

Return type:

dict

evaluate(args)

Evaluate the agent on a parameter point

Parameters:

args (tuple) – Tuple containing the index of the agent, the agent, the index of the parameter point and the parameter point

Returns:

Tuple containing the index of the parameter point and the results of the agent on the parameter point

Return type:

tuple

get_initial_data_from_existing_data_turbo()

get_tracking_metrics(agents)

Extract tracking metrics from agents

Parameters:

agents (list) – List of Agent objects

Returns:

List of tracking metric names formatted with agent name prefix

Return type:

list

optimize()

Run the optimization process using the agents and the parameters. The optimization process uses the Ax library. The optimization process runs the agents in parallel if the parallel attribute is True. The optimization process runs using the parameters, agents, models, n_batches, batch_size, max_parallelism, model_kwargs_list, model_gen_kwargs_list, name and kwargs attributes of the class.

Raises:

ValueError – If the number of batches and the number of models are not the same

optimize_sequential()

Run the optimization process using the agents and the parameters. The optimization process uses the Ax library. The optimization process runs the agents in parallel if the parallel attribute is True. The optimization process runs using the parameters, agents, models, n_batches, batch_size, max_parallelism, model_kwargs_list, model_gen_kwargs_list, name and kwargs attributes of the class.

Raises:

ValueError – If the number of batches and the number of models are not the same

optimize_turbo(acq_turbo='ts', force_continue=False, kwargs_turbo_state={}, kwargs_turbo={})

Run the optimzation using Turbo. This is based on the Botorch implementation of Turbo. See https://botorch.org/docs/tutorials/turbo_1/ for more details.

Parameters:

• acq_turbo (str, optional) – The acquisition function to use can be ‘ts’ or ‘ei’, by default ‘ts’

• force_continue (bool, optional) – If True, the optimization will continue even if a restart is triggered, by default False

• kwargs_turbo_state (dict, optional) – The kwargs to use for the TurboState, by default {} can be: - length: float, by default 0.8 - length_min: float, by default 0.5**7 - length_max: float, by default 1.6 - success_tolerance: int, by default 10

• kwargs_turbo (dict, optional) – The kwargs to use for the Turbo, by default {}

Raises:

• ValueError – Turbo does not support parameter constraints

• ValueError – Turbo does not support outcome constraints

• ValueError – Turbo only supports single objective optimization

• ValueError – Turbo only supports 2 models

• ValueError – Turbo only supports Sobol as the first model

• ValueError – Turbo only supports BoTorch as the second model

update_params_with_best_balance(return_best_balance=False)

Update the parameters with the best balance of all metrics. The best balance is defined by ranking the results for each metric and taking the parameters that has the lowest sum of ranks.

Raises:

ValueError – We need at least one metric to update the parameters

optimpv.axBOtorch.axBOtorchOptimizer.generate_batch(state, model, X, Y, batch_size, n_candidates=None, num_restarts=10, raw_samples=512, acqf='ts', device=None, dtype=None, minimize=False)

Generate a batch of points using the TURBO algorithm. The batch is generated using either Thompson sampling or Expected Improvement.

Parameters:

• state (TurboState) – Current state of the optimization process

• model (GPyTorchModel) – GPyTorch model for the function

• X (torch.Tensor) – Evaluated points on the domain [0, 1]^d

• Y (torch.Tensor) – Function values

• batch_size (int) – Number of points to generate

• n_candidates (int, optional) – Number of candidates for Thompson sampling, by default None

• num_restarts (int, optional) – Number of restarts for the optimization, by default 10

• raw_samples (int, optional) – Number of raw samples for the optimization, by default 512

• acqf (str, optional) – Acquisition function to use can be “ts” or “ei”, by default “ts”

• device (torch.device, optional) – Device to use for the generated points, by default None

• dtype (torch.dtype, optional) – Data type of the generated points, by default None

• minimize (bool, optional) – Whether to minimize or maximize the function, by default False

Returns:

Generated points in the range [0, 1]^d

Return type:

torch.Tensor

Raises:

• AssertionError – If the acquisition function is not “ts” or “ei”

• ValueError – If the acquisition function is not “ts” or “ei”

optimpv.axBOtorch.axBOtorchOptimizer.get_initial_points(dim, n_pts, seed=None, device=None, dtype=None)

Generate initial points using Sobol sequence.

Parameters:

• dim (int) – Number of dimensions

• n_pts (int) – Number of points to generate

• seed (int, optional) – Random seed, by default None

• device (torch.device, optional) – Device to use for the generated points, by default None

• dtype (torch.dtype, optional) – Data type of the generated points, by default None

Returns:

Generated points in the range [0, 1]^d

Return type:

torch.Tensor

optimpv.axBOtorch.axBOtorchOptimizer.update_state(state, Y_next)

Update the state of the optimization process based on the new observations.

For TURBO optimization only. The state is updated based on the success or failure of the new observations.

Parameters:

• state (TurboState) – Current state of the optimization process

• Y_next (torch.Tensor) – New observations

Returns:

Updated state of the optimization process

Return type:

TurboState

optimpv.axBOtorch.axUtils module

Utility functions for the Ax/Botorch library

optimpv.axBOtorch.axUtils.ConvertParamsAx(params)

Convert the params to the format required by the Ax/Botorch library

Parameters:

params (list of Fitparam() objects) – list of Fitparam() objects

Returns:

list of dictionaries with the following keys:

’name’: string: the name of the parameter ‘type’: string: ‘range’ or ‘fixed’ ‘bounds’: list of float: the lower and upper bounds of the parameter

Return type:

list of dict

optimpv.axBOtorch.axUtils.CreateObjectiveFromAgent(agent)

Create the objective function from the agent

Parameters:

agent (Agent() object) – the agent object

Returns:

the objective function

Return type:

function

optimpv.axBOtorch.axUtils.get_df_ax_client_metrics(params, ax_client, all_metrics)

Get the dataframe from the ax client and rescale the parameters to their true scale. The dataframe contains the parameters and the objective values. The parameters are rescaled to their true scale. The objective values are the mean of the objective values. The dataframe is returned as a pandas dataframe.

Parameters:

• params (list of FitParam() objects) – List of Fitparam() objects.

• ax_client (object) – Ax client object.

• all_metrics (list of str) – List of objective names.

Returns:

Dataframe containing the parameters and the objective values.

Return type:

pd.DataFrame

Raises:

ValueError – trying to rescale a parameter that is not int or float

optimpv.axBOtorch.axUtils.get_df_from_ax(params, optimizer)

Get the dataframe from the ax client and rescale the parameters to their true scale. The dataframe contains the parameters and the objective values. The parameters are rescaled to their true scale. The objective values are the mean of the objective values. The dataframe is returned as a pandas dataframe.

Parameters:

• params (list of FitParam() objects) – List of Fitparam() objects.

• optimizer (object) – Optimizer object from optimpv.axBOtorch.axBOtorch The optimizer object contains the ax client and the experiment.

Returns:

Dataframe containing the parameters and the objective values.

Return type:

pd.DataFrame

Raises:

ValueError – trying to rescale a parameter that is not int or float

Module contents