Agent¶

Ax Agent (Recommended)¶

class blop.ax.Agent(readables, dofs, objectives, db, dof_constraints=None, digestion=<function default_digestion_function>, digestion_kwargs=None)[source]

Bases: object

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

Attributes:

readableslist[Readable]: The readables to use for acquisition. These should be the minimal set of readables that are needed to compute the objectives.
dofslist[DOF]: The degrees of freedom that the agent can control, which determine the output of the model.
objectiveslist[Objective]: The objectives which the agent will try to optimize.
dbBroker | Container: The databroker or tiled instance to read back data from a Bluesky run.
dof_constraintsSequence[DOFConstraint], optional: Constraints on DOFs to refine the search space.
digestionDigestionFunction: The function to produce objective values from a dataframe of acquisition results.
digestion_kwargsdict: Additional keyword arguments to pass to the digestion function.

configure_experiment(name=None, description=None, experiment_type=None, owner=None)[source]

Configure an experiment. Uses the active DOFs and objectives.

Parameters:

namestr, optional: A name for the experiment.
descriptionstr, optional: A description for the experiment.
experiment_typestr, optional: The type of experiment.
ownerstr, optional: The owner of the experiment.

See also

ax.Client.configure_experiment: The Ax method to configure an experiment.
ax.Client.configure_optimization: The Ax method to configure the optimization.
ax.Client.configure_metrics: The Ax method to configure tracking metrics.

acquire_baseline(parameterization=None, arm_name=None)[source]

Measure a baseline of the objectives.

Parameters:

parameterizationTParameterization, optional: Move the DOFs to the given parameterization, if provided.
arm_namestr, optional: A name for the arm to distinguish it from other arms.

suggest(num_points=None)[source]

Returns a set of points in the input space, to be evaulated next.

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.

get_next_trials(max_trials=1, **kwargs)[source]

Get the next trial(s) to run.

Parameters:

max_trialsint, optional: The maximum number of trials to get. Higher values can lead to more efficient data acquisition, but slower optimization progress.

Returns:

dict[int, TParameterization]: A dictionary mapping trial indices to their suggested parameterizations.

ask(n=1)[source]

Get the next trial(s) to run.

Deprecated since version v0.8.1: Use suggest or get_next_trials instead.

Parameters:

nint, optional: The number of trials to get. Higher values can lead to more efficient data acquisition, but slower optimization progress.

Returns:

dict[int, TParameterization]: A dictionary mapping trial indices to their suggested parameterizations.

ingest(points)[source]

Ingest a set of points into the experiment. Either from previously suggested points or from an external source.

If points are from an external source, the dictionaries must contain keys for the DOF names.

Parameters:

pointslist[dict]: A list of dictionaries, each containing at least the outcome(s) of a trial and optionally the associated parameterization

complete_trials(trials, outcomes=None, **kwargs)[source]

Complete trial(s) by providing the outcomes.

Parameters:

trialsdict[int, TParameterization]: A dictionary mapping trial indices to their suggested parameterizations.
outcomesdict[int, TOutcome], optional: A dictionary mapping trial indices to their outcomes. If not provided, the trial will be completed with no outcomes.

See also

ax.Client.complete_trial: The Ax method to complete a trial.

tell(trials, outcomes=None)[source]

Complete trial(s) by providing the outcomes.

Deprecated since version v0.8.1: Use ingest or complete_trials instead.

Parameters:

trialsdict[int, TParameterization]: A dictionary mapping trial indices to their suggested parameterizations.
outcomesdict[int, TOutcome], optional: A dictionary mapping trial indices to their outcomes. If not provided, the trial will be completed with no outcomes.

See also

ax.Client.complete_trial: The Ax method to complete a trial.

attach_data(data)[source]

Attach data to the experiment in the form of new trials. Useful for resuming an experiment from a previous state or manually adding data.

Parameters:

datalist[tuple[TParameterization, TOutcome]]: A dataset of input and output examples.

See also

ax.Client.attach_trial: The Ax method to attach a trial.
ax.Client.complete_trial: The Ax method to complete a trial.

learn(iterations=1, n=1)[source]

Learn by running trials and providing the outcomes.

Parameters:

iterationsint, optional: The number of optimization iterations to run.
nint, optional: The number of trials to run per iteration. Higher values can lead to more efficient data acquisition, but slower optimization progress.

Returns:

Generator[dict[int, TOutcome], None, None]: A generator that yields the outcomes of the trials.

acquire(trials, per_step=None)[source]

Acquire data given a set of trials. Deploys the trials in a single Bluesky run and returns the outcomes of the trials computed by the digestion function.

Parameters:

trialsdict[int, TParameterization]: A dictionary mapping trial indices to their suggested parameterizations.

Returns:

MsgGenerator[dict[int, TOutcome]]: A message generator that yields the outcomes of the trials.

See also

blop.plans.acquire: The Bluesky plan to acquire data.

compute_analyses(analyses, display=True)[source]

Compute analyses for the experiment.

Parameters:

analyseslist[Analysis]: The Ax analyses to compute
displaybool: Show plots in an interactive environment.

Returns:

list[AnalysisCard]: The computed analysis cards

See also

ax.analysis: The Ax analysis module which contains many pre-built analyses.
ax.analysis.Analysis: The Ax analysis class to create custom analyses.
ax.analysis.AnalysisCard: The Ax analysis card class which contains the raw and computed data.

plot_objective(x_dof_name, y_dof_name, objective_name)[source]

Plot the predicted objective as a function of the two DOFs.

Parameters:

x_dof_namestr: The name of the DOF to plot on the x-axis.
y_dof_namestr: The name of the DOF to plot on the y-axis.
objective_namestr: The name of the objective to plot.

Returns:

list[AnalysisCard]: The computed analysis cards

See also

ax.analysis.ContourPlot: Pre-built analysis for plotting the objective as a function of two parameters.
ax.analysis.AnalysisCard: The Ax analysis card class which contains the raw and computed data.

configure_generation_strategy(method='fast', initialization_budget=None, initialization_random_seed=None, initialize_with_center=True, use_existing_trials_for_initialization=True, min_observed_initialization_trials=None, allow_exceeding_initialization_budget=False, torch_device=None)[source]

Implicitly configure the models and algorithms used to generate new points. Based on the settings and the DOF configuration, an appropriate generation strategy is chosen.

Parameters:

methodLiteral[“balanced”, “fast”, “random_search”], optional: Methods for generating new points.
initialization_budgetint | None, optional: The number of points to generate during the initial exploration phase. Can be set to 0 to disable initialization (when attaching pre-existing data, for example).
initialization_random_seedint | None, optional: The random seed for initialization.
initialize_with_centerbool, optional: Use the first point to sample the center of the search space defined by the DOFs.
use_existing_trials_for_initializationbool, optional: Use the pre-existing trials to build the initial models.
min_observed_initialization_trialsint | None, optional: The minimum number of trials to observe before building the initial models.
allow_exceeding_initialization_budgetbool, optional: Allow the initialization budget to be exceeded, when determined necessary.
torch_devicestr | None, optional: The device to use for PyTorch tensors (e.g. “cuda”, “cpu”, etc.).

See also

set_generation_strategy: Explicitly set the generation strategy for the experiment.
ax.Client.configure_generation_strategy: The Ax method to configure the generation strategy.

set_generation_strategy(generation_strategy)[source]

Explicitly set the generation strategy for the experiment. This allows for finer-grained control over the models and algorithms used to generate new points.

Familiarity with Ax and BoTorch internals is recommended prior to using this method.

Parameters:

generation_strategyGenerationStrategy: The generation strategy to use for the experiment. See this tutorial for more details.

See also

configure_generation_strategy: Configure an implicit generation strategy for the experiment.
ax.Client.set_generation_strategy: The Ax method to set the generation strategy.

summarize()[source]

View of the experiment state.

NOTE: This method is a convenience method for inspecting the experiment state. It is not recommended to use this for downstream analysis.

Returns:

pd.DataFrame: A dataframe of the experiment state containing a parameterization per row.

See also

ax.Client.summarize: The Ax method to summarize the experiment state.

Agent (Deprecated)¶

class blop.agent.Agent(dofs, objectives, db=None, detectors=None, acquisition_plan=<function default_acquisition_plan>, digestion=<function default_digestion_function>, digestion_kwargs=None, verbose=False, enforce_all_objectives_valid=True, exclude_pruned=True, model_inactive_objectives=False, tolerate_acquisition_errors=False, sample_center_on_init=False, trigger_delay=0, train_every=3)[source]

Bases: BaseAgent

A Bayesian optimization agent.

Deprecated since version v0.8.0: This class is deprecated and will be removed in Blop v1.0.0. Use blop.ax.Agent instead.

Parameters:

dofsSequence[DOF]: The degrees of freedom that the agent can control, which determine the output of the model.
db: Broker | Container: A Tiled or Databroker object
objectivesSequence[Objective]: The objectives which the agent will try to optimize.
acquisition_planCallable, optional: A plan that samples the beamline for some given inputs, by default default_acquisition_plan. Called directly in Agent, used only by __name__ in BlueskyAdaptiveAgent. Default: default_acquisition_plan
digestionCallable, optional: A function to digest the output of the acquisition, taking a DataFrame as an argument, by default default_digestion_function Default: default_digestion_function
digestion_kwargsdict, optional: Some kwargs for the digestion function, by default {} Default: False
verbosebool, optional: To be verbose or not, by default False Default: False
enforce_all_objectives_validbool, optional: Whether the agent should exclude from fitting points with one or more invalid objectives. Default: True
exclude_prunedbool, optional: Whether to exclude from fitting points that have been pruned after running agent.prune(). Default: True
model_inactive_objectivesbool, optional: Whether the agent should update models for outcomes that affect inactive objectives. Default: False
tolerate_acquisition_errorsbool, optional: Whether to allow errors during acquistion. If True, errors will be caught as warnings. Default: False
sample_center_on_initbool, optional: Whether to sample the center of the DOF limits when the agent has no data yet. Default: False
train_everyint, optional: How many samples to take before retraining model hyperparameters. Default: 4

property table: dict[str, Any]

refresh()[source]

redigest()[source]

learn(acqf='qei', n=1, iterations=1, upsample=1, force_train=False, append=True, hypers=None, route=True, **acqf_kwargs)[source]

This returns a Bluesky plan which iterates the learning algorithm, looping over ask -> acquire -> tell.

For example:

RE(agent.learn(‘qr’, n=16)) RE(agent.learn(‘qei’, n=4, iterations=4))

Parameters:

acqfstr: A valid identifier for an implemented acquisition function.
nint: How many points to sample on each iteration.
iterations: int: How many iterations of the learning loop to perform.
train: bool: Whether to train the models upon telling the agent.
append: bool: If True, add the new data to the old data. If False, replace the old data with the new data.
data_file: str: If supplied, read a saved data file instead of running the acquisition plan.
hypers_file: str: If supplied, read a saved hyperparameter file instead of fitting models. NOTE: The agent will assume these hyperparameters a priori for the rest of the run, and not try to fit a model.

view(item='mean', cmap='turbo', max_inputs=65536)[source]

Use napari to see a high-dimensional array.

Parameters:

itemstr: The thing to be viewed. Either ‘mean’, ‘error’, or an acquisition function.

acquire(points)[source]

Acquire and digest according to the self’s acquisition and digestion plans.

Parameters:

acquisition_inputs: A 2D numpy array comprising inputs for the active and non-read-only DOFs to sample.

load_data(data_file, append=True)[source]

reset()[source]: Reset the agent.

benchmark(output_dir='./', iterations=16, per_iter_learn_kwargs_list=({'acqf': 'qr', 'n': 32}, {'acqf': 'qei', 'iterations': 4, 'n': 1}))[source]

Iterate over having the agent learn from scratch, and save the results to an output directory.

Parameters:

output_dir: Where to save the agent output.
iterationsint: How many benchmarks to run
per_iter_learn_kwargs_list:: A list of kwargs to pass to the agent.learn() method that the agent will run sequentially for each iteration.

property model: ModelListGP: A model encompassing all the fitnesses and constraints.

posterior(x)[source]

A model encompassing all the objectives. A single GP in the single-objective case, or a model list.

property pareto_mask: Tensor: Returns a mask of all points that satisfy all constraints and are Pareto efficient. A point is Pareto efficient if it is there is no other point that is better at every objective.

property pareto_front: Any: A subset of the data table containing only points on the Pareto front.

property min_ref_point: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]

property all_objectives_valid: Tensor: A mask of whether all objectives are valid for each data point.

save_data(path)[source]

Save the sampled inputs and targets of the agent to a file, which can be used to initialize a future agent.

forget(last=None, index=None, train=True)[source]

Make the agent forget some data.

Parameters:

index: An list of sample indexes to forget about.
lastint: Forget the last n=last points.

property hypers: dict[str, dict[str, dict[str, Tensor]]]: Returns a dict of all the hyperparameters for each model in each objective.

save_hypers(filepath)[source]

Save the agent’s fitted hyperparameters to a given filepath.

static load_hypers(filepath)[source]

Load hyperparameters from a file.

property all_acqfs: DataFrame: Description and identifiers for all supported acquisition functions.

property best: Any: Returns all data for the best point.

property best_inputs: dict[Hashable, Any]: Returns the value of each DOF at the best point.

go_to(**positions)[source]

Set all settable DOFs to a given position. DOF/value pairs should be supplied as kwargs, e.g. as

RE(agent.go_to(some_dof=x1, some_other_dof=x2, …))

go_to_best()[source]

Go to the position of the best input seen so far.

plot_objectives(axes=(0, 1), **kwargs)[source]

Plot the sampled objectives

Parameters:

axes: A tuple specifying which DOFs to plot as a function of. Can be either an int or the name of DOFs.

plot_acquisition(acqf='ei', axes=(0, 1), **kwargs)[source]

Plot an acquisition function over test inputs sampling the limits of the parameter space.

Parameters:

acqf: Which acquisition function to plot. Can also take a list of acquisition functions.
axes: A tuple specifying which DOFs to plot as a function of. Can be either an int or the name of DOFs.

plot_validity(axes=(0, 1), **kwargs)[source]

Plot the modeled constraint over test inputs sampling the limits of the parameter space.

Parameters:

axes: A tuple specifying which DOFs to plot as a function of. Can be either an int or the name of DOFs.

plot_history(**kwargs)[source]

Plot the improvement of the agent over time.

property latent_transforms: dict[str, Kernel]

plot_pareto_front(**kwargs)[source]

Plot the improvement of the agent over time.

argmax_best_f(weights='default')

ask(acqf='qei', n=1, route=True, sequential=True, upsample=1, **acqf_kwargs)

Ask the agent for the best point to sample, given an acquisition function.

Parameters:

acqf_identifier: Which acquisition function to use. Supported values can be found in agent.all_acqfs
nint: How many points you want
routebool: Whether to route the supplied points to make a more efficient path.
sequentialbool: Whether to generate points sequentially (as opposed to in parallel). Sequential generation involves finding one points and constructing a fantasy posterior about its value to generate the next point.

best_f(weights='default')

Return the best point (the one with highest fitness given that it satisfies the most constraints)

constraint(x)

property evaluated_constraints: Tensor: Return a tensor of booleans that evaluates whether each collected outcome satisfies its constraint.

property fitness_model: Model

fitness_scalarization(weights='default')

property input_normalization: Normalize

Suitably transforms model inputs to the unit hypercube.

For modeling:

Always normalize between min and max values. This is always inside the trust domain, sometimes smaller.

For sampling:

Settable: normalize between search bounds Read-only: constrain to the readback value

property n_samples: int: Returns the number of samples in the agent’s table.

prune(pruning_objs=None, thresholds=None)[source]

Prune low-fidelity datapoints from model fitting

pruned_mask()

property random_ref_point: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]

raw_inputs(index=None, **subset_kwargs)

Get the raw, untransformed inputs for a DOF (or for a subset).

raw_targets(index=None, **subset_kwargs)

Get the raw, untransformed targets for an objective (or for a subset of objectives) as a tensor.

raw_targets_dict(index=None, **subset_kwargs)

Get the raw, untransformed targets for an objective (or for a subset of objectives) as a dict.

sample(n=3200, normalize=False, method='quasi-random')

Returns a (…, 1, n_active_dofs) tensor of points sampled within the parameter space.

Parameters:

nint: How many points to sample.
methodstr: How to sample the points. Must be one of ‘quasi-random’, ‘random’, or ‘grid’.
normalize: bool: If True, sample the unit hypercube. If False, sample the parameter space of the agent.

property sample_domain: Tensor: Returns a (2, n_active_dof) array of lower and upper bounds for dofs. Read-only DOFs are set to exactly their last known value. Discrete DOFs are relaxed to some continuous domain.

scalarized_fitnesses(weights='default', constrained=True)

Return the scalar fitness for each sample, scalarized by the weighting scheme.

If constrained=True, points that satisfy the most constraints are preferred to those that satisfy fewer.

tell(data={}, x={}, y={}, metadata={}, append=True, force_train=False)

Inform the agent about new inputs and targets for the model.

If run with no arguments, it will just reconstruct all the models.

Parameters:

xdict: A dict keyed by the name of each DOF, with a list of values for each DOF.
ydict: A dict keyed by the name of each objective, with a list of values for each objective.
append: bool: If True, will append new data to old data. If False, will replace old data with new data.
train: bool: Whether to train the models on construction.
hypers:: A dict of hyperparameters for the model to assume a priori, instead of training.

train_inputs(index=None, **subset_kwargs)

A two-dimensional tensor of all DOF values for training on.

train_targets(index=None, **subset_kwargs)

Returns the values associated with an objective name as an (n_samples, n_objective) tensor.

train_targets_dict(index=None, **subset_kwargs)

Returns the values associated with an objective name.

update_models(force_train=False)

We don’t want to retrain the models on every call of everything, but if they are out of sync with the DOFs then we should.