Agent

class blop.ax.Agent(readables, dofs, objectives, evaluation, acquisition_plan=None, dof_constraints=None, outcome_constraints=None, **kwargs)

Bases: object

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

The Agent is the main entry point for setting up and running Bayesian optimization using Blop. It coordinates the DOFs, objectives, evaluation function, and optimizer to perform intelligent exploration of the parameter space.

Parameters:

readablesSequence[Readable]

The readables to use for acquisition. These should be the minimal set of readables that are needed to compute the objectives.

dofsSequence[DOF]

The degrees of freedom that the agent can control, which determine the search space.

objectivesSequence[Objective]

The objectives which the agent will try to optimize.

evaluationEvaluationFunction

The function to evaluate acquired data and produce outcomes.

acquisition_planAcquisitionPlan | None, optional

The acquisition plan to use for acquiring data from the beamline. If not provided, blop.plans.default_acquire() will be used.

dof_constraintsSequence[DOFConstraint] | None, optional

Constraints on DOFs to refine the search space.

outcome_constraintsSequence[OutcomeConstraint] | None, optional

Constraints on outcomes to be satisfied during optimization.

**kwargsAny

Additional keyword arguments to configure the Ax experiment.

See also

blop.ax.dof.RangeDOF

For continuous parameters.

blop.ax.dof.ChoiceDOF

For discrete parameters.

blop.ax.objective.Objective

For defining objectives.

blop.ax.optimizer.AxOptimizer

The optimizer used internally.

blop.plans.optimize

Bluesky plan for running optimization.

Notes

For more complex setups, you can configure the Ax client directly via self.ax_client.

For complete working examples of creating and using an Agent, see the tutorial documentation, particularly Run a simple experiment with Bluesky.

property readables: Sequence[Readable]

property dofs: Sequence[DOF]

property objectives: Sequence[Objective]

property evaluation_function: EvaluationFunction

property acquisition_plan: AcquisitionPlan | None

property dof_constraints: Sequence[DOFConstraint] | None

property outcome_constraints: Sequence[OutcomeConstraint] | None

property ax_client: Client

to_optimization_problem()

Construct an optimization problem from the agent.

Creates an immutable blop.protocols.OptimizationProblem that encapsulates all components needed for optimization. This is typically used internally by optimization plans.

Returns:

OptimizationProblem

An immutable optimization problem that can be deployed via Bluesky.

See also

blop.protocols.OptimizationProblem

The optimization problem dataclass.

blop.plans.optimize

Uses the optimization problem to run optimization.

suggest(num_points=1)

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

Uses the Bayesian optimization algorithm to suggest promising points based on all previously acquired data. Each suggestion includes an “_id” key for tracking.

Parameters:

num_pointsint, optional

The number of points to suggest. Default is 1. Higher values enable batch optimization but may reduce optimization efficiency per iteration.

Returns:

list[dict]

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

ask(n=1)

Get the next trial(s) to run.

Deprecated since version v0.8.1: Use suggest 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)

Ingest evaluation results into the optimizer.

Updates the optimizer’s model with new data. Can ingest both suggested points (with “_id” key) and external data (without “_id” key).

Parameters:

pointslist[dict]

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

Notes

This method is typically called automatically by optimize(). Manual usage is only needed for custom workflows or when ingesting external data.

For complete examples, see Attach external data to experiments.

tell(trials, outcomes=None)

Complete trial(s) by providing the outcomes.

Deprecated since version v0.8.1: Use ingest 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.

learn(iterations=1, n=1)

Learn by running trials and providing the outcomes.

Deprecated since version v0.9.0: Use optimize instead.

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.

acquire_baseline(parameterization=None)

Acquire a baseline reading for reference.

Acquires data at a specific parameterization (or current positions) to establish a baseline for comparison. Useful for relative outcome constraints.

Parameters:

parameterizationdict[str, Any] | None, optional

The DOF values to move to before acquiring baseline. If None, acquires at current positions.

Yields:

Msg

Bluesky messages for the run engine.

See also

blop.plans.acquire_baseline

The underlying Bluesky plan.

optimize(iterations=1, n_points=1)

Run Bayesian optimization.

Performs iterative optimization by suggesting points, acquiring data, evaluating outcomes, and updating the model. This is the main method for running optimization with an agent.

Parameters:

iterationsint, optional

The number of optimization iterations to run. Default is 1. Each iteration suggests, evaluates, and learns from n_points.

n_pointsint, optional

The number of points to evaluate per iteration. Default is 1. Higher values enable batch optimization but may reduce optimization efficiency per iteration.

Yields:

Msg

Bluesky messages for the run engine.

See also

blop.plans.optimize

The underlying Bluesky optimization plan.

suggest

Get point suggestions without running acquisition.

ingest

Manually ingest evaluation results.

Notes

This is the primary method for running optimization. It handles the full loop of suggesting points, acquiring data, evaluating outcomes, and updating the model.

For complete examples, see Run a simple experiment with Bluesky.

plot_objective(x_dof_name, y_dof_name, objective_name, *args, **kwargs)

Plot the predicted objective as a function of two DOFs.

Creates a contour plot showing the model’s prediction of an objective across the space defined by two DOFs. Useful for visualizing the optimization landscape.

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.

*argsAny

Additional positional arguments passed to Ax’s compute_analyses.

**kwargsAny

Additional keyword arguments passed to Ax’s compute_analyses.

Returns:

list[AnalysisCard]

The computed analysis cards containing the plot data.

See also

ax.analysis.ContourPlot

Pre-built analysis for plotting objectives.

ax.analysis.AnalysisCard

Contains the raw and computed data.