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 inresult["run_uids"].
QueueserverClient#
- class bluesky_adaptive.queueserver.QueueserverClient(re_manager_api)[source]#
Bases:
objectHandles 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
QueueserverOptimizationRunner#
- class bluesky_adaptive.queueserver.QueueserverOptimizationRunner(optimization_problem, queueserver_client)[source]#
Bases:
objectRuns 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()andsubmit_suggestions_async()run it on the caller’s event loop;run()andsubmit_suggestions()start it on a shared background event loop and return aconcurrent.futures.Future. Queueserver requests, optimizer calls, and the evaluation function are synchronous, so they run in worker threads viaasyncio.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.
- 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.Checkpointableprotocol.
- Returns:
- concurrent.futures.Future[OptimizationResult]
A future that resolves to an
OptimizationResultwhen all iterations complete, or afterstop()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 cancellingrun_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
OptimizationResultwhen 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()orsubmit_suggestions()resolves (andrun_async()orsubmit_suggestions_async()returns) with a partialOptimizationResult, 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.