Ax Optimizer

class blop.ax.optimizer.AxOptimizer(parameters, objective, parameter_constraints=None, outcome_constraints=None, checkpoint_path=None, client_kwargs=None, **kwargs)

Bases: Optimizer, Checkpointable, CanRegisterSuggestions, TrialFaultAware

An optimizer that uses Ax as the backend for optimization and experiment tracking.

This is the built-in implementation of the blop.protocols.Optimizer protocol.

Parameters:

parametersSequence[RangeParameterConfig | ChoiceParameterConfig]

The parameters to optimize.

objectivestr

The objective to optimize.

parameter_constraintsSequence[str] | None, optional

The parameter constraints to apply to the optimization.

outcome_constraintsSequence[str] | None, optional

The outcome constraints to apply to the optimization.

checkpoint_pathstr | None, optional

The path to the checkpoint file to save the optimizer’s state to.

client_kwargsdict[str, Any] | None, optional

Additional keyword arguments to configure the Ax client.

**kwargsAny

Additional keyword arguments to configure the Ax experiment.

See also

blop.ax.Agent

High-level interface that uses AxOptimizer internally.

blop.protocols.Optimizer

The protocol this class implements.

classmethod from_checkpoint(checkpoint_path)

Load an optimizer from a checkpoint file.

Parameters:

checkpoint_pathstr

The path to the checkpoint file to load the optimizer from.

Returns:

AxOptimizer

An instance of the optimizer class, initialized from the checkpoint.

property checkpoint_path: str | None

The file path for saving and restoring optimizer state, or None if disabled.

property ax_client: Client

The underlying Ax Client used for experiment management.

property fixed_parameters: dict[str, Any] | None

Parameters held fixed during optimization, or None if all parameters are free.

suggest(num_points=None)

Get the next point(s) to evaluate in the search space.

Uses Ax’s Bayesian optimization to suggest promising points based on the current model and acquisition function.

Parameters:

num_pointsint | None, optional

The number of points to suggest. If not provided, will default to 1.

Returns:

list[dict]

A list of dictionaries, each containing a parameterization of a point to evaluate next. Each dictionary includes an “_id” key for tracking.

get_best_points()

Get a list of the optimal points found during optimization.

For single-objective optimization, returns a single best point. For multi-objective optimization, returns the Pareto-optimal set.

Returns:

list[tuple[int, TParameterization, TOutcome]]

Each element in the list is a tuple of:

• trial index (int)

• parameter values (dict)

• metric values (dict, where values may be (value, sem) tuples)

Raises:

ValueError

If the Ax client’s optimization has not been configured yet.

ingest(points)

Ingest evaluation results into the optimizer.

Updates Ax’s experiment with new data, which will be used to train the model for future suggestions. Handles both suggested points and external data.

Parameters:

pointslist[dict]

A list of dictionaries, each containing outcomes for a trial. For suggested points (from suggest()), include the “_id” key. For external data, include parameter names and objective values, and omit “_id”.

Notes

Points with "_id": "baseline" are treated as baseline trials for reference.

register_suggestions(suggestions)

Register manual suggestions with the Ax experiment.

Attaches trials to the experiment and returns the suggestions with “_id” keys added for tracking. This enables manual point injection alongside optimizer-driven suggestions.

Parameters:

suggestionslist[dict]

Parameter combinations to register. The “_id” key will be overwritten if present.

Returns:

list[dict]

The same suggestions with “_id” keys added.

register_failures(suggestions)

Register suggestions as failures.

Inherited from the trialfaultaware class to make sure either the Ax optimizer knows to either retry the trial or end the optimization context

Parameters:

suggestionslist[dict]

the trial id key must be present to pass back to the optimizer

checkpoint()

Save the optimizer’s state to JSON file.

reconfigure_search_space(parameter_mappings)

Update the bounds or values of existing parameters in the underlying experiment.

Parameters:

parameter_mappingsdict[str, tuple[float, float] | list[TParamValue]]

Mapping of parameter names to (lower, upper) bounds or a list of values depending on the parameter type.