RunEngine API Documentation

class bluesky.run_engine.RunEngine(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=None, scan_id_source=<function default_scan_id_source>, during_task=<function default_during_task>)[source]

The Run Engine execute messages and emits Documents.

Parameters:
md : dict-like, optional

The default is a standard Python dictionary, but fancier objects can be used to store long-term history and persist it between sessions. The standard configuration instantiates a Run Engine with historydict.HistoryDict, a simple interface to a sqlite file. Any object supporting __getitem__, __setitem__, and clear will work.

loop : asyncio event loop

e.g., asyncio.get_event_loop() or asyncio.new_event_loop()

preprocessors : list, optional

Generator functions that take in a plan (generator instance) and modify its messages on the way out. Suitable examples include the functions in the module bluesky.plans with names ending in ‘wrapper’. Functions are composed in order: the preprocessors [f, g] are applied like f(g(plan)).

context_managers : list, optional

Context managers that will be entered when we run a plan. The context managers will be composed in order, much like the preprocessors. If this argument is omitted, we will use a user-oriented handler for SIGINT. The elements of this list will be passed this RunEngine instance as their only argument. You may pass an empty list if you would like a RunEngine with no signal handling and no context managers.

md_validator : callable, optional

a function that raises and prevents starting a run if it deems the metadata to be invalid or incomplete Expected signature: f(md) Function should raise if md is invalid. What that means is completely up to the user. The function’s return value is ignored.

scan_id_source : callable, optional

a function that will be used to calculate scan_id. Default is to increment scan_id by 1 each time. However you could pass in a customized function to get a scan_id from any source. Expected signature: f(md) Expected return: updated scan_id value

during_task : callable, optional

Function to be run to block the main thread during RE.__call__

The required signature is

def blocking_func(ev: Threading.Event) -> None:
    "Returns when ev is set"
The default value handles the cases of:
  • Matplotlib is not imported (just wait on the event)
  • Matplotlib is imported, but not using a Qt, notebook or ipympl backend (just wait on the event)
  • Matplotlib is imported and using a Qt backend (run the Qt app on the main thread until the run finishes)
  • Matplotlib is imported and using a nbagg or ipympl backend ( wait on the event and poll to push updates to the browser)
Attributes:
md

Direct access to the dict-like persistent storage described above

record_interruptions

False by default. Set to True to generate an extra event stream that records any interruptions (pauses, suspensions).

state

{‘idle’, ‘running’, ‘paused’}

suspenders

Read-only collection of bluesky.suspenders.SuspenderBase objects which can suspend and resume execution; see related methods.

preprocessors : list

Generator functions that take in a plan (generator instance) and modify its messages on the way out. Suitable examples include the functions in the module bluesky.plans with names ending in ‘wrapper’. Functions are composed in order: the preprocessors [f, g] are applied like f(g(plan)).

msg_hook

Callable that receives all messages before they are processed (useful for logging or other development purposes); expected signature is f(msg) where msg is a bluesky.Msg, a kind of namedtuple; default is None.

state_hook

Callable with signature f(new_state, old_state) that will be called whenever the RunEngine’s state attribute is updated; default is None

waiting_hook

Callable with signature f(status_object) that will be called whenever the RunEngine is waiting for long-running commands (trigger, set, kickoff, complete) to complete. This hook is useful to incorporate a progress bar.

ignore_callback_exceptions

Boolean, False by default.

loop : asyncio event loop

e.g., asyncio.get_event_loop() or asyncio.new_event_loop()

max_depth

Maximum stack depth; set this to prevent users from calling the RunEngine inside a function (which can result in unexpected behavior and breaks introspection tools). Default is None. For built-in Python interpreter, set to 2. For IPython, set to 11 (tested on IPython 5.1.0; other versions may vary).

pause_msg : str

The message printed when a run is interrupted. This message includes instructions of changing the state of the RunEngine. It is set to bluesky.run_engine.PAUSE_MSG by default and can be modified based on needs.

commands:

The list of commands available to Msg.

__call__(self, plan, subs=None, /, **metadata_kw)[source]

Execute a plan.

Any keyword arguments will be interpreted as metadata and recorded with any run(s) created by executing the plan. Notice that the plan (required) and extra subscriptions (optional) must be given as positional arguments.

Parameters:
plan : generator (positional only)

a generator or that yields Msg objects (or an iterable that returns such a generator)

subs : callable, list, or dict, optional (positional only)

Temporary subscriptions (a.k.a. callbacks) to be used on this run. For convenience, any of the following are accepted:

  • a callable, which will be subscribed to ‘all’
  • a list of callables, which again will be subscribed to ‘all’
  • a dictionary, mapping specific subscriptions to callables or lists of callables; valid keys are {‘all’, ‘start’, ‘stop’, ‘event’, ‘descriptor’}
Returns:
uids : list

list of uids (i.e. RunStart Document uids) of run(s)

The RunEngine maintains a callback registry of functions that receive any Documents generated by plan execution. These methods add and remove functions from that registry.

subscribe(self, func, name='all')[source]

Register a callback function to consume documents.

Changed in version 0.10.0: The order of the arguments was swapped and the name argument has been given a default value, 'all'. Because the meaning of the arguments is unambiguous (they must be a callable and a string, respectively) the old order will be supported indefinitely, with a warning.

Parameters:
func: callable

expecting signature like f(name, document) where name is a string and document is a dict

name : {‘all’, ‘start’, ‘descriptor’, ‘event’, ‘stop’}, optional

the type of document this function should receive (‘all’ by default)

Returns:
token : int

an integer ID that can be used to unsubscribe

unsubscribe(self, token)[source]

Unregister a callback function its integer ID.

Parameters:
token : int

the integer ID issued by RunEngine.subscribe()

When the RunEngine is in a paused state, it can be resumed or stopped in various ways using these methods:

resume(self)[source]

Resume a paused plan from the last checkpoint.

Returns:
uids : list

list of Header uids (a.k.a RunStart uids) of run(s)

abort(self, reason='')[source]

Stop a running or paused plan and mark it as aborted.

stop(self)[source]

Stop a running or paused plan, but mark it as successful (not aborted).

halt(self)[source]

Stop the running plan and do not allow the plan a chance to clean up.

The RunEngine can suspend and resume plan execution in response to external changes. See Automated Suspension.

install_suspender(self, suspender)[source]

Install a ‘suspender’, which can suspend and resume execution.

Parameters:
suspender : bluesky.suspenders.SuspenderBase
remove_suspender(self, suspender)[source]

Uninstall a suspender.

Parameters:
suspender : bluesky.suspenders.SuspenderBase
clear_suspenders(self)[source]

Uninstall all suspenders.

These methods are used internally to pause or suspend the RunEngine. Typically the user accomplishes this with Ctrl+C or by installing suspenders, respectively. For special applicaitons, they can be called directly.

request_pause(self, defer=False)[source]

Command the Run Engine to pause.

This function is called by ‘pause’ Messages. It can also be called by other threads. It cannot be called on the main thread during a run, but it is called by SIGINT (i.e., Ctrl+C).

If there current run has no checkpoint (via the ‘clear_checkpoint’ message), this will cause the run to abort.

Parameters:
defer : bool, optional

If False, pause immediately before processing any new messages. If True, pause at the next checkpoint. False by default.

request_suspend(self, fut, *, pre_plan=None, post_plan=None, justification=None)[source]

Request that the run suspend itself until the future is finished.

The two plans will be run before and after waiting for the future. This enable doing things like opening and closing shutters and resetting cameras around a suspend.

Parameters:
fut : asyncio.Future
pre_plan : iterable or callable, optional

Plan to execute just before suspending. If callable, must take no arguments.

post_plan : iterable or callable, optional

Plan to execute just before resuming. If callable, must take no arguments.

justification : str, optional

explanation of why the suspension has been requested

These methods may be used to register custom commands to supplement or replace the built-in commands recognized by the RunEngine.

register_command(self, name, func)[source]

Register a new Message command.

Parameters:
name : str
func : callable

This can be a function or a method. The signature is f(msg).

unregister_command(self, name)[source]

Unregister a Message command.

Parameters:
name : str

These methods may be used to list the commands available, or print a summary as to what they do.

print_command_registry(self, verbose=False)[source]

This conveniently prints the command registry of available commands.

Parameters:
Verbose : bool, optional
verbose print. Default is False

Examples

>>> from bluesky import RunEngine
>>> RE = RunEngine()
>>> # Print a very verbose list of currently registered commands
>>> RE.print_command_registry(verbose=True)
commands

The list of commands available to Msg.

Examples

>>> from bluesky import RunEngine
>>> RE = RunEngine()
>>> # to list commands
>>> RE.commands

A RunEngine encapsulates a Dispatcher for emitting any Documents generated by plan execution. The methods RunEngine.subscribe() and RunEngine.unsubscribe(), documented above, are aliases to the corresponding methods on the RunEngine’s Dispatcher.

class bluesky.run_engine.Dispatcher[source]

Dispatch documents to user-defined consumers on the main thread.

subscribe(self, func, name='all')[source]

Register a callback function to consume documents.

Changed in version 0.10.0: The order of the arguments was swapped and the name argument has been given a default value, 'all'. Because the meaning of the arguments is unambiguous (they must be a callable and a string, respectively) the old order will be supported indefinitely, with a warning.

Changed in version 0.10.0: The order of the arguments was swapped and the name argument has been given a default value, 'all'. Because the meaning of the arguments is unambiguous (they must be a callable and a string, respectively) the old order will be supported indefinitely, with a warning.

Parameters:
func: callable

expecting signature like f(name, document) where name is a string and document is a dict

name : {‘all’, ‘start’, ‘descriptor’, ‘event’, ‘stop’}, optional

the type of document this function should receive (‘all’ by default).

Returns:
token : int

an integer ID that can be used to unsubscribe

See also

Dispatcher.unsubscribe()
an integer token that can be used to unsubscribe
unsubscribe(self, token)[source]

Unregister a callback function using its integer ID.

Parameters:
token : int

the integer ID issued by Dispatcher.subscribe()

unsubscribe_all(self)[source]

Unregister all callbacks from the dispatcher

process(self, name, doc)[source]

Dispatch document doc of type name to the callback registry.

Parameters:
name : {‘start’, ‘descriptor’, ‘event’, ‘stop’}
doc : dict