Included Example Agents#

Bluesky Adaptive provides several example agents that can be easily integrated into your experimental workflows. These agents demonstrate a range of functionalities from simple sequential decision-making to more complex data-driven approaches utilizing machine learning models. These can serve as primary examples for developing your own agents, or used directly in your experiments with minimal modifications. Below, we introduce and describe the functionality of these example agents.

Sequential Agent#

The SequentialAgentBase is designed for experiments requiring a predetermined sequence of measurements. This agent iteratively provides the next point in the sequence upon each ask and keeps track of the number of queries made. This is better served by actual plans since it is not particularly adaptive, but showcases the basic structure of an agent.

Key Features:#

Sequential Decision Making: Operates by following a pre-defined sequence of experimental conditions.
Boundary Checking: Optionally enforces relative bounds for the sequence values to ensure measurements remain within desired limits.
Progress Reporting: Provides a report on the percentage completion of the sequence.

Agent Mixin to take a pre-defined sequence and walk through it on ask.

Parameters:

sequenceSequence[Union[float, ArrayLike]]: Sequence of points to be queried
relative_boundsTuple[Union[float, ArrayLike]], optional: Relative bounds for the members of the sequence to follow, by default None

Attributes:

independent_cachelist: List of the independent variables at each observed point
observable_cachelist: List of all observables corresponding to the points in the independent_cache
sequenceSequence[Union[float, ArrayLike]]: Sequence of points to be queried
relative_boundsTuple[Union[float, ArrayLike]], optional: Relative bounds for the members of the sequence to follow, by default None
ask_countint: Number of queries this agent has made

Sklearn Estimator Agent#

The SklearnEstimatorAgentBase and its derivatives like DecompositionAgentBase and ClusterAgentBase utilize Scikit-learn models for data-driven decision-making. These agents are primarily passive, focusing on analyzing datasets through decomposition and clustering techniques.

Key Features:#

Integration with Scikit-learn: Leverages Sklearn estimators for data analysis.
Dataset Analysis: Performs tasks such as PCA or clustering to analyze the experimental dataset.
Model Parameter Adjustment: Allows for dynamic adjustment of model parameters.
Demonstrates Close and Restart Functionality: Demonstrates how to close and restart the agent when its parameters are updated such that its output documents will change shape (e.g., changing the number of componetns in a decomposition).

class bluesky_adaptive.agents.sklearn.SklearnEstimatorAgentBase(*, estimator: BaseEstimator, **kwargs)[source]#

Basic functionality for sklearn estimators. Maintains independent and dependent caches. Strictly passive agent with do ask mechanism: will raise NotImplementedError

Parameters:

estimatorsklearn.base.TransformerMixin: Estimator instance that inherits from TransformerMixin and BaseEstimator This model will be used to call fit transform. Common examples include PCA and NMF.

class bluesky_adaptive.agents.sklearn.DecompositionAgentBase(*, estimator: TransformerMixin, **kwargs)[source]#

Passive, report only agent that provide dataset analysis for decomposition.

Parameters:

estimatorsklearn.base.TransformerMixin: Estimator instance that inherits from TransformerMixin and BaseEstimator This model will be used to call fit transform. Common examples include PCA and NMF.

class bluesky_adaptive.agents.sklearn.ClusterAgentBase(*, estimator: ClusterMixin, **kwargs)[source]#

Passive, report only agent that provide dataset analysis for clustering.

Parameters:

estimatorsklearn.base.ClusterMixin: Estimator instance that inherits from ClusterMixin, TransformerMixin and BaseEstimator This model will be used to call fit transform. Common examples include kmeans.

BoTorch Agent#

The SingleTaskGPAgentBase demonstrates the integration of BoTorch for Bayesian optimization using Gaussian Processes (GP). This agent is suitable for optimizing experimental conditions based on a surrogate model of the experiment’s outcome. Specifically, it uses a single task GP, with a default UCB acquisition function, but can be customized to use other acquisition functions.

Key Features:#

Bayesian Optimization: Utilizes a GP-based surrogate model for decision-making.
Customizable Acquisition Function: Supports custom acquisition functions to dictate the exploration-exploitation balance.
Device Compatibility: Operates on either CPU or CUDA-enabled GPU devices for computation.
State Management: Manages and reports the state of the acquisition function for transparency and reproducibility.

class bluesky_adaptive.agents.botorch.SingleTaskGPAgentBase(*, bounds: Tensor, gp: SingleTaskGP | None = None, device: device | None = None, out_dim=1, partial_acq_function: Callable | None = None, num_restarts: int = 10, raw_samples: int = 20, **kwargs)[source]#

Single Task GP based Bayesian Optimization

Parameters:

boundstorch.Tensor: A 2 x d tensor of lower and upper bounds for each column of X
gpSingleTaskGP, optional: GP surrogate model to use, by default uses BoTorch default
devicetorch.device, optional: Device, by default cuda if avail
out_dimint, optional: Dimension of output predictions by surrogate model, by default 1
partial_acq_functionOptional[Callable], optional: Partial acquisition function that will take a single argument of a conditioned surrogate model. By default UCB with beta at 0.1
num_restartsint, optional: Number of restarts for optimizing the acquisition function, by default 10
raw_samplesint, optional: Number of samples used to instantiate the initial conditions of the acquisition function optimizer. For a discussion of num_restarts vs raw_samples, see: pytorch/botorch#366 Defaults to 20.

These example agents provided by Bluesky Adaptive offer a starting point for integrating intelligent, data-driven decision-making into your experimental setups. Whether your experiments require simple sequential steps, data analysis through machine learning models, or sophisticated optimization strategies, these agents serve as both a practical tool and a source of inspiration for developing your custom agents.