Protocols

AcquisitionPlan

class blop.protocols.AcquisitionPlan(*args, **kwargs)

Bases: Protocol

A protocol for custom data acquisition plans.

This protocol defines how to acquire data from the beamline. Most users will use the default blop.plans.default_acquire() plan, which performs a list scan over the suggested points. Custom implementations are only needed for specialized acquisition strategies (e.g., fly scans, complex detector configurations).

See also

blop.plans.default_acquire

Default acquisition plan implementation.

blop.ax.Agent

Accepts an optional acquisition plan during initialization.

Notes

The acquisition plan is a Bluesky plan that should move the movables to each suggested position and acquire data from the readables. It must return the UID of the Bluesky run so that the evaluation function can retrieve the data.

__call__(suggestions, movables, readables=None)

Acquire data for optimization.

This should be a Bluesky plan that moves the movables to each of their suggested positions and acquires data from the readables.

Parameters:

suggestions: list[dict]

A list of dictionaries, each containing the parameterization of a point to evaluate. The “_id” key is optional and can be used to identify each suggestion. It is suggested to add “_id” values to the run metadata for later identification of the acquired data.

movables: Sequence[NamedMovable]

The movables to move to their suggested positions.

readables: Sequence[Readable], optional

The readables that produce data to evaluate.

Returns:

str

The unique identifier of the Bluesky run.

EvaluationFunction

class blop.protocols.EvaluationFunction(*args, **kwargs)

Bases: Protocol

A protocol for transforming acquired data into measurable outcomes.

This protocol defines how to extract and compute optimization objectives from acquired data. Custom implementations are needed to define how your beamline data translates into the outcomes you want to optimize.

See also

blop.ax.Agent

Accepts an evaluation function during initialization.

Notes

The evaluation function is called after data acquisition to compute outcomes from the acquired data. It should extract relevant data from the Bluesky run and compute objective values and metrics for each suggestion.

Examples

See the tutorial documentation for complete examples of evaluation functions: Run a simple experiment with Bluesky

__call__(uid, suggestions)

Evaluate the data from a Bluesky run and produce outcomes.

Parameters:

uid: str

The unique identifier of the Bluesky run to evaluate.

suggestions: list[dict]

A list of dictionaries, each containing the parameterization of a point to evaluate. The “_id” key is optional and can be used to identify each suggestion.

Returns:

list[dict]

A list of dictionaries containing the outcomes of the run, one for each suggested parameterization. The “_id” key is optional and can be used to identify each outcome.

Optimizer

class blop.protocols.Optimizer(*args, **kwargs)

Bases: Protocol

A minimal optimizer interface for optimization.

This protocol defines the interface for optimizers in Blop. Most users will use the built-in blop.ax.optimizer.AxOptimizer, which provides Bayesian optimization via Ax. Custom implementations are only needed for specialized optimization algorithms.

See also

blop.ax.optimizer.AxOptimizer

Built-in Ax-based optimizer implementation.

blop.ax.Agent

High-level interface that uses AxOptimizer internally.

suggest(num_points=None)

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

The “_id” key is optional and can be used to identify suggested trials for later evaluation and ingestion.

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 must contain a unique “_id” key to identify each parameterization.

ingest(points)

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

The “_id” key is optional and can be used to identify points from previously suggested trials or to identify the point as a “baseline” trial.

Parameters:

pointslist[dict]

A list of dictionaries, each containing the outcomes of each suggested parameterization.

OptimizationProblem

class blop.protocols.OptimizationProblem(optimizer, movables, readables, evaluation_function, acquisition_plan=None)

Bases: object

An optimization problem to solve. Immutable once initialized.

This dataclass encapsulates all components needed for optimization into a single immutable structure. It is typically created via blop.ax.Agent.to_optimization_problem() and used with optimization plans like blop.plans.optimize().

Attributes:

optimizer: Optimizer

Suggests points to evaluate and ingests outcomes to inform the optimization.

movables: Sequence[NamedMovable]

Objects that can be moved to control the beamline using the Bluesky RunEngine. A subset of the movables’ names must match the names of suggested parameterizations.

readables: Sequence[Readable]

Objects that can be read to acquire data from the beamline using the Bluesky RunEngine.

evaluation_function: EvaluationFunction

A callable to evaluate data from a Bluesky run and produce outcomes.

acquisition_plan: AcquisitionPlan, optional

A Bluesky plan to acquire data from the beamline. If not provided, a default plan will be used.

See also

blop.ax.Agent.to_optimization_problem

Creates an OptimizationProblem from an Agent.

blop.plans.optimize

Bluesky plan that uses an OptimizationProblem.

optimizer: Optimizer

movables: Sequence[NamedMovable]

readables: Sequence[Readable]

evaluation_function: EvaluationFunction

acquisition_plan: AcquisitionPlan | None = None