Agent¶

Ax Agent (Recommended)¶

class blop.ax.Agent(readables, dofs, objectives, db, 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.
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.

ask(n=1)[source]

Get the next trial(s) to run.

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.

tell(trials, outcomes=None)[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.

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)[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:

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

See also

bluesky.plans.list_scan: The Bluesky plan to acquire data.
bluesky.utils.Msg: The Bluesky message type.

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.