Queueserver#

Warning

The queueserver integration is experimental. The API is not yet stable and may change in future releases without a deprecation period. It is not recommended for production use.

These classes implement the distributed optimization backend that connects Bluesky Adaptive to a remote Bluesky Queueserver. See the Asynchronous Optimization with Bluesky Queueserver tutorial for a full worked example.

OptimizationResult#

class bluesky_adaptive.queueserver.OptimizationResult(iterations_completed, num_points, uids)[source]#

The result of a completed or stopped optimization run.

Warning

This class is part of the experimental queueserver integration. The API may change in future releases without a deprecation period.

Parameters:
iterations_completedint

The number of suggest -> acquire -> ingest cycles that finished successfully. For a run stopped early via QueueserverOptimizationRunner.stop(), this reflects however many iterations completed before the stop.

num_pointsint

The number of points suggested per iteration.

uidstuple[str, …]

The queue item UIDs of the completed acquisitions, in order. Each item’s history_get() entry lists the UIDs of the runs it opened in result["run_uids"].

iterations_completed: int#
num_points: int#
uids: tuple[str, ...]#

QueueserverClient#

class bluesky_adaptive.queueserver.QueueserverClient(re_manager_api)[source]#

Bases: object

Handles communication with a Bluesky queueserver.

This class encapsulates queueserver communication: plan submission and environment checks. The queue must be running or have autostart enabled.

Warning

This class is part of the experimental queueserver integration. The API may change in future releases without a deprecation period.

Parameters:
re_manager_apibluesky_queueserver_api.zmq.REManagerAPI | bluesky_queueserver_api.http.REManagerAPI

Manager instance for communication with Bluesky Queueserver

check_environment()[source]#

Verify that the queueserver environment is ready.

Raises:
RuntimeError

If the queueserver environment is not open.

submit_plan(plan)[source]#

Submit a plan to the queueserver queue.

Parameters:
planBPlan

The plan to submit.

Returns:
str

The queue item UID assigned by the RE Manager.

QueueserverOptimizationRunner#

class bluesky_adaptive.queueserver.QueueserverOptimizationRunner(optimization_problem, queueserver_client)[source]#

Bases: object

Runs optimization loops through a Bluesky queueserver.

This class coordinates the optimization workflow by getting suggestions from the optimizer, submitting acquisition plans to the queueserver, and ingesting the outcomes the evaluation function returns for each submitted plan.

The loop is an asyncio coroutine. run_async() and submit_suggestions_async() run it on the caller’s event loop; run() and submit_suggestions() start it on a shared background event loop and return a concurrent.futures.Future. Queueserver requests, optimizer calls, and the evaluation function are synchronous, so they run in worker threads via asyncio.to_thread() and never block the event loop. A runner executes one loop at a time.

Warning

This class is part of the experimental queueserver integration. The API may change in future releases without a deprecation period.

Parameters:
optimization_problemQueueserverOptimizationProblem

The optimization problem to solve, containing the optimizer, actuators, sensors, and evaluation function.

queueserver_clientQueueserverClient

Client for communicating with the queueserver.

property optimization_problem: QueueserverOptimizationProblem#

The optimization problem being solved.

property current_iteration: int#

The current iteration number (0 if not running).

run(iterations=1, num_points=1, checkpoint_interval=None)[source]#

Run the optimization loop.

Validates the queueserver state and submits the first plan, then returns while the suggest -> acquire -> ingest cycle continues on a background event loop that calls the evaluation function with each submitted plan’s queue item UID. run_async() is the coroutine version.

Parameters:
iterationsint

Number of optimization iterations to run.

num_pointsint

Number of points to suggest per iteration.

checkpoint_intervalint | None

The number of iterations between optimizer checkpoints. If None, checkpoints will not be saved. Optimizer must implement the bluesky_adaptive.protocols.Checkpointable protocol.

Returns:
concurrent.futures.Future[OptimizationResult]

A future that resolves to an OptimizationResult when all iterations complete, or after stop() once the in-flight evaluation returns. If the optimization loop raises an unhandled exception the future will hold that exception and re-raise it on .result(). Cancelling the future cancels the loop like cancelling run_async().

Raises:
RuntimeError

If the queueserver environment is not ready.

ValueError

If required devices or plans are not available, or the suggestions are invalid.

async run_async(iterations=1, num_points=1, checkpoint_interval=None)[source]#

Run the optimization loop on the running event loop and return its result.

Coroutine version of run() for callers with a running event loop, such as Jupyter or a service; parameters and errors are the same, and loop errors are raised instead of held in a future. Cancelling it abandons the in-flight acquisition: its plan stays queued, its evaluation runs to completion in its worker thread, and its outcomes are not ingested.

submit_suggestions(suggestions)[source]#

Manually submit suggestions to the queue.

This method returns once the plan is submitted; a background event loop calls the evaluation function with the plan’s queue item UID and ingests the outcomes. submit_suggestions_async() is the coroutine version.

Parameters:
suggestionsSequence[Mapping]

Parameter combinations to evaluate. Can be:

  • Optimizer suggestions (with “_id” keys from suggest())

  • Manual points (without “_id”, requires CanRegisterSuggestions protocol)

Returns:
concurrent.futures.Future[OptimizationResult]

A future that resolves to an OptimizationResult when the acquisition completes. If an unhandled exception occurs the future will hold it and re-raise on .result().

async submit_suggestions_async(suggestions)[source]#

Manually submit suggestions to the queue on the running event loop and return the result.

Coroutine version of submit_suggestions() for callers with a running event loop, such as Jupyter or a service; parameters and errors are the same.

stop()[source]#

Stop the optimization loop gracefully.

No further plans are submitted, and the in-flight evaluation is not interrupted. After that evaluation returns and is ingested, the future returned by run() or submit_suggestions() resolves (and run_async() or submit_suggestions_async() returns) with a partial OptimizationResult, or with the evaluation’s exception. Plans already in the queue are not removed. Evaluation functions should bound their waits so that a stop takes effect. This method only sets a flag, so it can be called from any thread.