The ~bluesky.plan_stubs.wait plan accepts a new optional parameter,
Add an option to contingency_wrapper to not automatically re-raise if the except plan returns a value rather than raising its own exception.
Add support for new experimental document types, StreamResource and StreamDatum.
In v0.11.0 bluesky implemented a new Msg to declare streams proactively, rather than creating them implicitly while preparing to emit the first Event. Built-in plans were updated to use this approach. It had unintended downstream consequences. Specifically, some ophyd objects (notable AD) that were using the trigger method to sort out what the keys will be. If you call describe before trigger you get different answers so going all-in on this by default is a bit too aggressive. Pre-declaring streams is now opt-in, using the env var
Changed ~bluesky.bundlers to use event-model compose functions * In the run stop document, ‘num_events’ will now include streams even if they have no events associated with them. * Events produced by monitors are now checked against their corresponding Descriptor document. * In the run stop document, ‘num_changes’ will now contain descriptors even if they have no events associated with them. * Events produced by monitors are now checked against their corresponding Descriptor document.
If a collect message results in no document being collected, a RuntimeError was being raised. Now, no error is raised; this is considered a possibility in normal successful operation.
Fixed leak in registry used by
RE.subscribe, which would grow without bound
Fixed a documentation-build issue, which moved the minimum version of matplotlib required for documentation-building to 3.5.0 (Nov 2021).
Fixed bug in exception handling in
LiveGrids placing x-axis tick labels on all columns by @maffettone in https://github.com/bluesky/bluesky/pull/1548
Remove callable from plan signature for qserver by @maffettone in https://github.com/bluesky/bluesky/pull/1571
Propagate exception through failed status by @RAYemelyanova in https://github.com/bluesky/bluesky/pull/1570
Resume thresholds to suspender justification message by @tacaswell in https://github.com/bluesky/bluesky/pull/1554
Use Python version check rather than import error check to import Protocol by @callumforrester in https://github.com/bluesky/bluesky/pull/1585
Locatable protocol, message and plan stub by @coretl in https://github.com/bluesky/bluesky/pull/1536
Made protocol methods abstract by @evalott100 in https://github.com/bluesky/bluesky/pull/1562
Allow stage and unstage to return status objects by @tizayi in https://github.com/bluesky/bluesky/pull/1563
Add ability to pre-declare a stream by @tacaswell in https://github.com/bluesky/bluesky/pull/1542
Made changes to put back the support for remote Qt applications that required the Qt event loop top be kicked when included or meshed with a RemoteDispatcher by @RussBerg in https://github.com/bluesky/bluesky/pull/1495
Move fig_factory default resolution in BestEffortCallback by @tacaswell in https://github.com/bluesky/bluesky/pull/1569
Properly register user-supplied event loops
Removed status_tasks dequeue from RunEngine, fixing long-standing memory leak
No-longer pre-compute all axes when not snaking, lowering memory footprint for large scans
Removed support for Python < 3.8
the “resume” message which can only be used internally has been renamed to “_resume_from_suspender”.
Movable(which has long been deprecated for
bluesky.utils.is_movable) has been deleted
~bluesky.plan_stubs.trigger_and_read now drops the event if
describeraise an exception which results in the raised
Exceptionmaking it to the user in the case when the “baseline” preprocessor is used.
Fix off-by-one bug in ~bluesky.callbacks.best_effort.BesteffortCallback multi-axis layout.
Add async capability to protocols and use throughout code base.
Add type hints.
Add dependency extras.
Document pycertifspec as hardware interface.
Changed from using
versioneer.py(fix to support Python 3.11).
Implemented human-readable printable representation for
Fixed a small mistake in
Added documentation about intended behavior of fraction in the
watchmethod of the status object.
More fixes for Python 3.10 to propagate the
Added optional calculation of the derivative and its statistics (
fwhm, etc.) to
RunEngine.deferred_pause_requestedwhich may be useful for bluesky-queueserver.
Updated the tests to use databroker.temp instead of sqlite databroker.
xfailtest that uses removed API.
Fix descriptors for flyers that do not implement
Do not pass the
RunBundlerif we do not have to.
__call__now may return plan value, as toggled by new
call_returns_resultflag. Default behavior has not changed, but may change in a future release.
Enabled support of Python 3.9 and added it to the test matrix.
Update TOC links to blueskyproject.io.
Added release instructions.
README.mdand added the
Fixed missing log output for CLI ZMQ proxy.
Depreciated argument logfile of
Better behavior when zmq RemoteDispatcher receives malformed messages.
Tweak layout of plots produced by the Best-Effort Callback when showing many LiveGrids.
bluesky.simulators.check_limits()simulator now calls
obj.check_value()instead of looking at
When a document is emitted from a RunEngine, a log message is always issued. Previously, Resource and Datum documents were missed.
Various docstrings were fixed to match the actual function signatures.
bluesky.utils.is_movable()for checking with an object satifies the expected interfaced for a “movable” object now correctly treats the
positionattribute as optional.
Documentation about the expected interface for “movable” objects was incomplete and has been revised to match reality.
bluesky.utils.PersistentDicthas new methods
bluesky.utils.PersistentDict.flush()to syncing from and to disk. It flushes at garbage collection or system exit, which ensures that any values that have been mutated are updated on disk.
LiveGrid and LiveScatter failed to update
Expand the class of objects considered “moveable” to include those with expected attributes defined as instance attributes
:to be used in keynames and still format LiveTable.
Address use of
loopargument deprecated in Python 3.8.
bluesky.utilsis importable from a background thread. (Do not create an instance of ~bluesky.utils.DefaultDuringTask at import time.)
Incorrect implementation of
collect()has been corrected.
Missing implementation details of
collect()have been added.
rel_grid_scan()accept a new
snake_axesparameter, now matching what
rel_list_grid_scan()do. This can be used to control which axes follow a back-and-forth “snake-like” trajectory.
# Default - snaking is disabled grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, hw.motor2, 3, 5, 4) # Snaking is explicitely disabled grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, hw.motor2, 3, 5, 4, snake_axes=False) # Snaking can also be disabled by providing empty list of motors grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, hw.motor2, 3, 5, 4, snake_axes=) # Snaking is enabled for all motors except the slowest hw.motor grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, hw.motor2, 3, 5, 4, snake_axes=True) # Snaking is enabled only for hw.motor1 grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, hw.motor2, 3, 5, 4, snake_axes=[hw.motor1]) # Snaking is enabled only for hw.motor1 and hw.motor2 grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, hw.motor2, 3, 5, 4, snake_axes=[hw.motor1, hw.motor2])
The old (harder to read) way of specifying “snake” parameters, interleaved with the other parameters, is still supported for backward-compatibility.
grid_scan([hw.det], hw.motor, 1, 2, 5, hw.motor1, 7, 2, 10, True, hw.motor2, 3, 5, 4, False)
The two styles—interleaved parameters vs. the new
snake_axesparameter—cannot be mixed. Mixing them will cause a
ValueErrorto be raised.
Fixed a regression in v1.6.0 which accidentally broke some usages of the
per_stepparameter in scans.
Noneby mistake. It now returns the Run Start uid, as do all the other plans that module.
The most important change in this release is a complete reworking of how
bluesky interacts with the asyncio event loop. This resolves a long-running
issue of bluesky being incompatible with
tornado >4, which often tripped up
users in the context of using bluesky from Jupyter notebooks.
There are several other new features and fixes, including new plans and more helpful error messages, enumerated further below.
Event loop re-factor¶
RunEngine had been repeatedly starting and
stopping the asyncio event loop in
resume(). This worked, but is bad practice. It
complicates attempts to integrate with the event loop with other tools.
Further, because as of tornado 5, tornado reports its self as an asyncio event
loop so attempts to start another asyncio event loop inside of a task fails
which means bluesky will not run in a jupyter notebook. To fix this we now
continuously run the event loop on a background thread and the
RunEngine object manages the interaction with creating tasks
on that event loop. To first order, users should not notice this change,
however details of how manage both blocking the user prompt and how we
suspend processing messages from a plan are radically different.
One consequence of running the event loop on a background thread is
that the code in plans and the callbacks is executed in that thread as well.
This means that plans and callbacks must now be threadsafe.
Previously, we were running the asyncio event loop on the main thread and blocked until it returned. This meant that if you were using Matplotlib and Qt for plots they would effectively be “frozen” because the Qt event loop was not being given a chance to run. We worked around this by installing a ‘kicker’ task onto the asyncio event loop that would periodically spin the Qt event loop to keep the figures responsive (both to addition of new data from callbacks and from user interaction).
Now that we are running the event loop on a background thread this no longer works because the Qt event loop must be run on the main thread. Instead we use during_task to block the main thread by running the Qt event loop directly.
during_task kwarg to
We need to block the main thread in
resume()) until the user supplied plan is complete.
Previously, we would do this by calling
start the asyncio event loop. We would then stop the event loop an
the bottom of
RunEngine._run and in
request_pause() to un-block the main thread and return
control to the user terminal. Now we must find an alternative way to achieve
There is a a
threading.Event on the
will be set when the task for
RunEngine._run in completed,
however we can not simple wait on that event as that would again cause the Qt
windows to freeze. We also do not want to bake a Matplotlib / Qt dependency
directly into the
RunEngine so we added a hook, set at init
time, for an object expected to implement the method
While the RunEngine executes a plan, it is passed the
and is responsible for blocking until the Event is set. This function can do
other things (such as run the Qt event loop) during that time. The required
def block(ev: Threading.Event) -> None: "Returns when ev is set"
The default hook will handle the case of the Matplotilb Qt backend and the case of Matplotlib not being imported.
'wait_for' Msg now expects callables rather than futures¶
Messages are stashed and re-run when plans are interrupted which would result in re-using the coroutines passed through. This has always been broken, but due to the way were stopping the event loop to pause the scan it was passing tests.
Instead of directly passing the values passed into
now expect that the iterable passed in is callables with the signature:
def fut_fac() -> awaitable: 'This must work multiple times'
The persistent dict used by
RE.md must be thread-safe¶
RE.md is an ordinary dictionary, but any dict-like object may
be used. It is often convenient for the contents of that dictionary to persist
between sessions. To achieve this, we formerly recommended using
~historydict.HistoryDict is not threadsafe and is not compatible with
bluesky’s new concurrency model. We now recommend using
PersistentDict. See Persistence Between Sessions for
instructions on how to migrate existing metadata.
Callbacks must be thread-safe¶
Because callbacks now run on the background thread they must be
thread-safe. The place where this is most likely to come up is in the
context of plotting which generally creates a GUI window. Almost all
GUI frameworks insist that they only be interacted with only on the
main thread. In the case of Qt we provide
QtAwareCallback to manage
moving Qt work back to the main thread (via a Qt
Plans must be thread-safe¶
Because the plans now execute on the background thread they must be thread-safe if the touch any external state. Similarly the callbacks, we expect that the most likely place for this to fail is with plotting. In most cases this can be addressed by using a thread-safe version of the callback.
Added support for Multi-Run Plans.
Added better logging and convenience functions for managing it more easily. See Debugging and Logging.
bluesky.plans.count(), analogous to the
per_stepparameter supported by plans that do scans.
Added a new built-in RunEngine command,
RE_class, which sends the type of the
RunEngineinto the generator. This allows the plan to know if it is being consumed by the usual
RunEngine, a subclass, or some non-responsive consumer like
Raise a more helpful error message if the
numparameter given to
scan()is not a whole number, as can happen if
numis mistaken to mean “step size”.
Report the version of bluesky and (if available) ophyd in the metadata.
Add a more helpful error message if the value returned from some call to
Noneinstead of the expected dict.
If the user tries to start a
RemoteDispatcherafter it has been stopped, raise a more helpful error message.
stateattribute of the
RunEngineis now a read-only property, as it should have always been.
In the Best-Effort Callback, do not assume that the RunStart document includes
'scan_id', which is an optional key.
The commandline utility
bluesky-0MQ-proxynow works on Windows.
The IPython integrations have been updated for compatibility with IPython 7.
Added support for “adaptive fly scans” by enabling the
'collect'message to (optionally) return the Events it emitted.
Fixed bug in tqdm-based progress bar where tqdm could be handed a value it considered invalid.
Other API Changes¶
bluesky.callbacks.best_effort.PeakResults. It has always been
None(never implemented) and only served to cause confusion.
This release fixes a bug that resulted in no configuration data related to fly scans being added to descriptors.
Added support for Python 3.8 and the following for forward-compatibility with 1.6.0.
See the 1.5.6 GH milestone for the complete list of changes.
bluesky.utils.register_transform with IPython >= 7
Support Maplotlib 3.1 and above. (Do not use deprecated and removed aspect adjustable values.)
This release removes the dependency on an old version of the
library and requires the latest version of the
This release fixes compatibility with matplotlib 2.x; at least some matplotlib 2.x releases are not compatible with the matplotlib plotting callbacks in bluesky v1.5.1. This release of bluesky is compatible with all 2.x and 3.x releases.
This release contains bug fixes and documentation updates.
Use the ISO8601 delimiters for date in RE scans.
Pin jsonschema <3 due to its deprecations.
Stop using deprecated API in Matplotlib.
This release includes many documentation fixes and handful of new features, especially around improved logging.
Logging has been increased and improved.
A default handler is added to the
'bluesky'logger at import time. A new convenience function,
set_handler(), addresses common cases such as directing the log output to a file.
bluesky-0MQ-proxyscript now supports a
-v, --verboseoption, which logs every start and stop document received and a
-vvv(“very verbose”) option, which logs every document of every type.
The prefix on messages sent by
bluesky.callbacks.zmq.Publishercan be set to arbitrary bytes. (In previous versions, the prefix was hardcoded to an encoded combination of the hostname, process ID, and the Python object ID of a RunEngine instance.)
The RunEngine includes a human-readable, not-necessarily-unique
scan_idkey in the RunStart document. The source of the
scan_idis now pluggable via a new parameter,
scan_id_source. See RunEngine API Documentation for details.
The convenience function,
bluesky.utils.ts_msg_hook()accepts new parameter
filefor directing the output to a file instead of the standard out.
It is possible to use those callbacks that do not require matplotlib without importing it.
Fixed BestEffortCallback’s handling of integer data in plots.
Fixed invalid escape sequence that produced a warning in Python 3.6.
The signature of
bluesky.callbacks.zmq.RemoteDispatcherhas been changed in a non-backward-compatible way. The parameters for filtering messages by
run_engine_idhave been replaced by one new parameter,
The default value of
True, meaning that the
RunEngine.logis not disabled by default.
bluesky.callbacks.zmq.Publisheraccepts an optional RunEngine instance, which the Publisher subscribes to automatically. This parameter has been deprecated; users are now encouraged to subscribe the publisher to the RunEngine manually, in the normal way (
RE.subscribe(publisher)). The parameter may be removed in a future release of bluesky.
This release fixes a single regression introduced in v1.4.0. We recommend all users upgrade.
Fix a critical typo that made
Note that the 1.4.x series is not compatible with newer versions of matplotlib; it needs a version lower than 3.1.0 due to an API change in matplotlib. The 1.5.x series is compatible with matplotlib versions before and after the change.
Added ability to control ‘sense’ of
LiveGrid(ex “positive goes down and to the right”) to match the coordinates in the hutch.
Learned how to specify the serializer / deserializer for the zmq publisher / client.
Added flag to
ramp_plan()to control if a data point is taken before the ramp starts.
Ensure order stability in
get_labeled_devices()on all supported versions of Python.
Fixed typos, dev requirements, and build details.
Fixed show-shopping RunEngine bug in flyer asset collection. (The impact of this bug is expected to be low, as there are no flyers with asset collection yet and the bug was discovered while writing the first one.)
Fixed packaging issue where certain important files (notably
requirements.txt) were not included in the source tarball.
Made BestEffortCallback swallow errors related to matplotlib’s “tight layout” if the occur — better to show a messy plot than error out.
Revised behavior of magics that integrate with ophyd’s experimental “labels” feature. The most important difference is that the
%wamagic now traverses the children of labeled devices to find any sub-devices that are positioners.
Fixed race condition where monitored signals could emit an Event document before the corresponding Event Descriptor document.
Addressed incompatibilities with upcoming release of Python, 3.7.
When used with ophyd v1.2.0 or later, emit Resource and Datum documents through the RunEngine. Previously, ophyd would insert these documents directly into a database. This left other consumers with only partial information (for example, missing file paths to externally-stored data) and no guarantees around synchronization. Now, ophyd need not interact with a database directly. All information flows through the RunEngine and out to any subscribed consumers in a deterministic order.
New Msg commands,
remove_suspender, allow plans to temporarily add and remove Suspenders.
The RunEngine’s signal handling (i.e. Ctrl+C capturing) is now configurable. The RunEngine accepts a list of
context_managersthat it will enter and exit before and after running. By default, it has one context manager that handles Ctrl+C. To disable Ctrl+C handling, pass in an empty list instead. This can also be used to inject other custom behavior.
Add new plans:
When resuming after a suspender, call
resume()on all devices (if present).
Fixed BEC LiveGrid plot for a motor with one step.
A codepath in
LiveFitthat should have produced a warning produced an error instead.
User-defined callbacks subscribed to the RunEngine
'all'stream must accept documents with names
'bulk_datum'. It does not necessarily have to heed their contents, but it must not fall over if it receives one.
The IPython “magics”, always marked as experimental, have been reworked. Instead of relying on the singleton lists,
BlueskyMagics.detectors, the magics now scrape the user namespace for objects that implement the
_ophyd_labels_interface. See IPython ‘Magics’ [Experimental] for the new usage. The magics will revert to their old behavior if the singleton lists are non-empty, but they will produce a warning. The old behavior will be removed in a future release.
Refreshed documentation with a new Tutorial section.
Better validation of user-defined
per_stepfunctions and more informative error messages to match.
Fix axes orientation in
BestEffortCallbackdisplay multi-motor scans properly.
Fix bug in
ts_msg_hook()where it conflated month and minute. Also, include sub-second precision.
Avoid situation where plan without hints caused the
BestEffortCallbackto error instead of do its best to guess useful behavior.
Skip un-filled externally-stored data in
LiveTable. This fixes a bug where it is expecting array data but gets UUID (
datum_id) and errors out.
caching_repeater()plan has been deprecated because it is incompatible with some preprocessors. It will be removed in a future release of bluesky. It was not documented in any previous releases and rarely if ever used, so the impact of this removal is expected to be low.
This release fixes small bugs in v1.0.0 and introduces one new feature. The API changes or deprecations are not expected to affect many users.
Add a new command to the
'drop', which jettisons the currently active event bundle without saving. This is useful for workflows that generate many readings that can immediately be categorized as not useful by the plan and summarily discarded.
Fix the hint for
inner_product_scan(), which previously used a default hint that was incorrect.
Breaking Changes and Deprecations¶
tune_centroid(), change the meaning of the
step_factorparameter to be the factor to reduce the range of each successive iteration. Enforce bounds on the motion, and determine the centroid from each pass separately.
SupplementalDatapreprocessor inserts its instructions in a more logical order: first baseline readings, then monitors, then flyers. Previously, the order was reversed.
SuspendInBandhas been renamed to
SuspendWhenOutsideBandto make its meaning more clear. Its behavior has not changed: it suspends when a value exits a given range. The original, confusing name now issues a warning.
SuspendOutBand, which counter-intuitively suspends when a value enters a given range, has been deprecated. (If some application is found for this unusual scenario, the user can always implement a custom suspender to handle it.)
This tag marks an important release for bluesky, signifying the conclusion of the early development phase. From this point on, we intend that this project will be co-developed between multiple facilities. The 1.x series is planned to be a long-term-support release.
This is the last release before 1.0.0. It contains major restructurings and general clean-up.
Breaking Changes and Deprecations¶
bluesky.plansmodule has been split into
bluesky.plans— plans that create a run, such as
bluesky.preprocessors— plans that take in other plans and motify them, such as
bluesky.plan_stubs— small plans meant as convenient building blocks for creating custom plans, such as
bluesky.cntx, containing legacy APIs to plans that were deprecated in a previous release and will be removed in a future release.
The RunEngine raises a
RunEngineInterruptedexception when interrupted (e.g. paused). The optional argument
raise_if_interruptedhas been removed.
bluesky.callbacks.scientifichas been removed.
PeakStatshas been moved to
plot_peak_stats()has been moved to bluesky.callbacks.mpl_plotting.
The synthetic ‘hardware’ objects in
bluesky.exampleshave been relocated to ophyd (bluesky’s sister package) and aggressively refactored to be more closely aligned with the behavior of real hardware. The
Moverclasses have been removed in favor of
stub_decorator()that strips open_run/close_run and stage/unstage messages out of a plan, so that it can be reused as part of a larger plan that manages the scope of a run manually.
tune_centroid()plan that iteratively finds the centroid of a single peak.
Allow devices with couple axes to be used in N-dimensional scan plans.
contingency_decorator()for richer cleanup specification.
The number of events in each event stream is recorded in the RunStop document under the key ‘num_events’.
Make the message shown when the RunEngine is paused configurable via the attribute
Fix ordering of dimensions in
Show Figures created internally.
Support a negative direction for adaptive scans.
Validate that all descriptors with a given (event stream) name have consistent data keys.
exit_statusfield in RunStop metadata based on which termination method was called (abort, stop, halt).
LiveFitPlothandles updates more carefully.
bluesky.callbackspackage has been split up into more modules. Shim imports maintain backward compatibility, except where noted in the section on API Changes above.
Matplotlib is now an optional dependency. If it is not importable, plotting-related callbacks will not be available.
An internal change to the RunEngine supports ophyd’s new Status object API for adding callbacks.
plan_mutator()more flexible. (See docstring.)
This is a small release with bug fixes and UI improvements.
Fix bug wherein BestEffortCallback tried to plot strings as floats. The intended behavior is to skip them and warn.
Include a more informative header in BestEffortCallback.
Include an ‘Offset’ column in %wa output.
This release is equivalent to v0.10.2. The number was skipped due to packaging problems.
Automatic best-effort visualization and peak-fitting is available for all plans, including user-defined ones.
The “SPEC-like” API has been fully removed, and its most useful features have been applied to the library in a self-consistent way. See the next section for detailed instructions on migrating.
Improved tooling for streaming documents over a network for live processing and visualization in a different process or on a different machine.
The modules implementing what was loosely dubbed a “SPEC-like” interface (
bluesky.global_state) have been entirely removed. This approach was insufficently similar to SPEC to satisfy SPEC users and confusingly inconsistent with the rest of bluesky.
The new approach retains the good things about that interface and makes them available for use with all plans consistently, including user defined ones. Users who have been fully utilitzing these “SPEC-like” plans will notice four differences.
gs.DETS. Just use your own variable for detectors. Instead of:
# OLD ALTERNATIVE, NO LONGER SUPPORTED from bluesky.global_state import gs from bluesky.spec_api import ct gs.DETS = # a list of some detectors RE(ct())
from bluesky.plans import count dets = # a list of some detectors RE(count(dets))
Notice that you can use multiple lists to enable easy task switching. Instead of continually updating one global list like this:
# OLD ALTERNATIVE, NO LONGER SUPPORTED gs.DETS = # some list of detectors RE(ct()) gs.DETS.remove(some_detector) gs.DETS.append(some_other_detector) RE(ct())
you can define as many lists as you want and call them whatever you want.
d1 = # a list of some detectors d2 = # a list of different detectors RE(count(d1)) RE(count(d2))
Automatic baseline readings, concurrent monitoring, and “flying” can be set up uniformly for all plans.
Formerly, a list of devices to read at the beginning and the end of each run (“baseline” readings), a list of signals to concurrent monitor, and a list of “flyers” to run concurrently were configured like so:
# OLD ALTERNATIVE, NO LONGER SUPPORTED from bluesky.spec_api import ct gs.BASELINE_DEVICES = # a list of devices to read at start and end gs.MONTIORS = # a list of signals to monitor concurrently gs.FLYERS = # a list of "flyable" devices gs.DETS = # a list of detectors RE(ct()) # monitoring, flying, and baseline readings are added
And formerly, those settings only affected the behavior of the “SPEC-like” plans, such as
ascan. They were ignored by their counterparts
scan, as well as user-defined plans. This was not desirable!
This scheme has been replaced by the supplemental data, which can be used to globally modify all plans, including user-defined ones.
from bluesky.plans import count # one-time configuration from bluesky import SupplementalData sd = SupplementalData() RE.preprocessors.append(sd) # interactive use sd.monitors = # a list of signals to monitor concurrently sd.flyers = # a list of "flyable" devices sd.baseline = # a list of devices to read at start and end dets = # a list of detectors RE(count(dets)) # monitoring, flying, and baseline readings are added
Automatic live visualization and peak analysis can be set up uniformly for all plans.
Formerly, the “SPEC-like” plans such as
ascanautomatically set up a suitable table and a plot, while their “standard” vanilla counterparts,
bluesky.plans.scan()required explicit, detailed instructions to do so. Now, a best-effort table and plot can be made for all plans, including user-defined ones, by invoking this simple configuration:
from bluesky.plans import count # one-time configuration from bluesky.callbacks.best_effort import BestEffortCallback bec = BestEffortCallback() RE.subscribe(bec) # interactive use dets = # a list of detectors RE(count(dets), num=5)) # automatically prints table, shows plot
bec.enable()to temporarily toggle the output off and on.
Peak anallysis, now computed automatically by the BestEffortCallback above, can be viewed with a keyboard shortcut. The peak statistics, formerly encapsulated in
gs.PS, are now organized differently.
For each plot, simple peak-fitting is performed in the background. Of course, it may or may not be applicable depending on your data, and it is not shown by default. To view fitting annotations in a plot, click the plot area and press Shift+P. (Lowercase p is a shortcut for “panning” the plot.)
To access the peak-fit statistics programmatically, use
bec.peaks. For convenience, you may alias this like:
peaks = bec.peaks
peaks, access various statistics like:
peaks.com peaks.cen peaks.max peaks.min
Each of these is a dictionary with an entry for each field that was fit. For example, the ‘center of mass’ peak statistics for a field named
'ccd_stats1_total'would be accessed like
The functions and classes in the module
bluesky.callbacks.brokerrequire a instance of
Brokerto be passed in as an argument. They used to default to the ‘singleton’ instance via
from databroker import db, which is now a deprecated usage in databroker.
The plan preprocessors
configure_count_time_decoratorwere moved to
bluesky.spec_api, reverting a change made in v0.9.0.
The 0MQ pubsub integration classes
RemoteDispatcherhave been overhauled. They have been moved from
bluesky.callbacks.zmqand their signatures have been changed to match similar utilities in the pydata ecosystem. See the Enhancements section for more information.
bluesky.qt_kickerhas been removed. Its former contents are avaiable in
bluesky.utils. The module was originally deprecated in April 2016, and it has been issuing warnings about this change since.
bluesky.plans.inputhas been renamed
bluesky.plans.input_planto avoid shadowing a builtin if the module is bulk-imported. The plan was previously undocumented and rarely used, so the impact of this change on users is expected to be small.
bluesky.plan_toolshas been renamed
bluesky.simualtors. In the new module,
bluesky.plan_tools.print_summary`()has been renamed
bluesky.simulators.summarize_plan(). The old names are supported in this release, with a warning, but will be removed in a future release.
The Object-Orientated plans (
Scan, etc.) have been deprecated and will be removed in a future release. Their documentation has been removed.
The plan context managers (
stage_context, etc.) have been deprecated and will be removed in a future release. They were never documented or widely used.
bluesky.Dispatcher.subscribe()(which is encapsulated into
bluesky.run_engine.RunEngineand inherited by
bluesky.callbacks.zmq.RemoteDispatcher) has a new signature. The former signature was
subscribe(name, func). The new signature is
subscribe(func, name='all'). Because the meaning of the arguments is unambigious (they must be a callable and a string, respectively) the old order will be supported indefeinitely, with a warning.
A progress bar add-on is available.
x='time'. It can set t=0 to the UNIX epoch or to the start of the run. It also accepts
x='seq_num'—a synonym for
x=None, which remains the default.
A new simulator
bluesky.simulators.check_limits()verifies that a plan will not try to move a movable device outside of its limits.
A new plan,
bluesky.plan.mvr(), has been added as a relative counterpart to
The 0MQ pubsub integration classes
bluesky.callbacks.zmq.RemoteDispatcherhave been simplified. A new class
bluesky.callbacks.zmq.Proxyand command-line utility
bluesky-0MQ-proxyhas been added to streamline configuration.
Metadata recorded by many built-in plans now includes a new item,
'hints', which is used by the best-effort callback to produce useful visualizations. Additionally, the built-in examples devices have a new hints attribute. Its content may change or expand in future releases as this new feature is explored.
Some IPython magics mimicing the SPEC API have been added. These are experimental and may be altered or removed in the future.
Using the “fake sleep” feature of simulated Movers (motors) caused them to break.
requirements.txtfailed to declare that bluesky requires matplotlib.
The metadata reported by step scans that used to be labeled
num_stepsis now renamed
num_points, generally considered a less ambiguous name. Separately,
num_interals(which one might mistakenly assume is what was meant by
num_steps) is also stored.
If some plan or callback has hung the RunEngine and blocked its normal ability to respond to Ctrl+C by pausing, it is not possible to trigger a “halt” (emergency stop) by hammering Ctrl+C more than ten times.
Fix bug where failed or canceled movements could cause future executions of the RunEngine to error.
Fix bug in
plan_mutatorso that it properly handles return values. One effect of this fix is that
baseline_wrapperproperly passed run uids through.
Fix bug in
LiveFitthat broke multivariate fits.
Minor fixes to example detectors.
KeyboardInterruptexception captured during a run used to cause the RunEngine to pause. Now it halts instead.
Nonlinear least-squares minimization callback
RunEngine.preprocessorslist that modifies all plans passed to the RunEngine.
RunEngine.state_hookto monitor state changes, akin to
finalize_wrapperwhich allows pauses the RunEngine before performing any cleanup, making it easier to debug.
Added many more examples and make it easier to create simulated devices that generate interesting simulated data. They have an interface closer to the real devices implemented in ophyd.
mv, a convenient plan for moving multiple devices in parallel.
RunEngine.max_depthto raise an error if the RunEngine thinks it is being called from inside a function.
The ‘monitor’ functionality was completely broken, packing configuration into the wrong structure and starting seq_num from 0 instead of 1, which is the (regrettable) standard we have settled on.
The RunEngine coroutines no longer mutate the messages they receive.
Fix race condition in
Fix bugs in several callbacks that caused them not to work on saved documents from the databroker. Also, make them call
super()to play better with multiple inheritance in user code.
RunEngine.ignore_callback_exceptionsnow defaults to False.
complete, related to fly scans, previously had
wait=Trueby default, although its documentation indicated that
Falsewas the default. The code has been changed to match the documentation. Any calls to
completethat are expected to be blocking should be updated with the keyword
Completely change the API of
Mover, the classes for definding simulated devices.
The bluesky interface now expects the
stopmethod on a device to accept an optional
The optional, undocumented
LivePlothas been deprecated and will be removed in a future release. An
axargument has been added. Additionally, the axes used by
LiveScatteris configurable through a new, optional
The “shortcut” where mashing Ctrl+C three times quickly ran
RE.abort()has been removed.
Change the default stream name for monitors to
signal_name>-monitor(underscore vs. dash). The impact of this change is minimal because, as noted above, the monitor functionality was completely broken in previous releases.
Much-expanded and overhauled documentation.
install_nb_kickerto get live-updating matplotlib figures in the notebook while the RunEngine is running.
Simulated hardware devices
Movercan be easily customized to mock a wider range of behaviors, for testing and demos.
Integrate the SPEC API with mew global state attribute
Callbacks that use the databroker accept an optional
Brokerinstance as an argument.
Minor fix in the tilt computation for spiral scans.
Expost ‘tilt’ option through SPEC-like API
The “infinite count” (
num=None) should spawn a LivePlot.
finalize_decoratoraccepts a callable (e.g., generator function) and does not accept an iterable (e.g., generator instance)
gs.FLYERSintegration to the SPEC API (accidentally removed).
The API for the simulated hardware example devices
Moverhas been changed to make them more general.
Change how “subscription factories” are handled, making them configurable through global state.
Make PeakStats configurable through global state.
Add an experimental utility for passing documents over a network and processing them on a separate process or host, using 0MQ.
monitor_during_wrapperand corresponding decorator.
stage_wrapperand corresponding decorator.
Built-in plans return the run uid that they generated.
Add a new
ramp_planfor taking data while polling the status of a movement.
Boost performance by removing unneeded “sleep” step in message processing.
Fix bug related to rewinding in preparation for resuming.
planifydecorator and the plan context managers. These were experimental and ultimately proved problematic because they make it difficult to pass through return values cleanly.
Remove “lossy” subscriptions feature, rendered unnecessary by the utility for processing documents in separate processes (see Enhancements, above).
make_decoratorreturn proper decorators. The original implementation returned functions that could not actually be used as decorators.
This release contained only a minor UX fix involving more informative error reporting related to Area Detector plugin port configuration.
Address the situation where plan “rewinding” after a pause or suspension interacted badly with some devices. There are now three ways to temporarily turn off rewinding: a Msg with a new ‘rewindable’ command; a special attribute on the device that the
trigger_and_readplan looks for; and a special exception that devices can raise when their
pausemethod is called. All three of these features should be considered experimental. They will likely be consolidated in the future once their usage is tested in the wild.
Add new plan wrappers and decorators:
Fix bug where RunEngine was put in the “running” state, encountered an error before starting the
_runcoroutine, and thus never switch back to “idle.”
Ensure that plans are closed correctly and that, if they fail to close themselves, a warning is printed.
Allow plan to run its cleanup messages (
finalize) when the RunEngine is stopped or aborted.
When an exception is raised, give each plan in the plan stack an opportunity to handle it. If it is handled, carry on.
twwas not passing its parameters through to the underlying
Silenced un-needed suspenders warnings
Fix bug in separating devices
Reduce unneeded usage of
Don’t emit create/save messages with no reads in between.
Re-work exception handling in main run engine event loop.
LiveTableonly displays data from one event stream.
Remove used global state attribute
Fix “infinite count”,
Allow the same data keys to be present in different event streams. But, as before, a given data key can only appear once per event.
Make SPEC-style plan
ctimplement baseline readings, referring to
Upon resuming after a deferred pause, clear the deferred pause request.
Plans were reimplemented as simple Python generators instead of custom Python classes. The old “object-oriented” plans are maintained for back-compatibility. See plans documentation to review new capabilities.
SPEC-style plans are now proper generators, not bound to the RunEngine.
bluesky.register_mdswhose usage can be replaced by:
import metadatastore.commands; RE.subscribe_lossless('all', metadatastore.commands.insert)
In all occurrences, the argument
block_grouphas been renamed
groupfor consistency. This affects the ‘trigger’ and ‘set’ messages.
The (not widely used)
Centerplan has been removed. It may be distributed separately in the future.
Calling a “SPEC-like” plan now returns a generator that must be passed to the RunEngine; it does not execute the plan with the global RunEngine in gs.RE. There is a convenience wrapper available to restore the old behavior as desired. But since that usage renders the plans un-composable, it is discouraged.
The ‘time’ argument of the SPEC-like plans is a keyword-only argument.
The following special-case SPEC-like scans have been removed
They can be defined in configuration files as desired, and in that location they will be easier to customize.
describemethod on flyers, which returns an iterable of dicts of data keys for one or more descriptors documents, has been renamed to
describe_collectto avoid confusion with
describeon other devices, which returns a dict of data keys for one descriptor document.
An obscure feature in
RunEngine.request_pausehas been removed, which involved removing the optional arguments
Address serious performance problem in
Stage the ultimate parent (“root”) when a device is staging its child, making it impossible to leave a device in a partially-staged state.
Give every event stream a
Record a mapping of device/signal names to ordered data keys in the EventDescriptor.
LiveRasteraccount for “snaked” trajectories.
PeakStats.comis a scalar, not a single-element array.
Restore Python 3.4 compatibility.
RunEngine.persistent_fields; all fields in
RE.mdpersist between runs by default.
No metadata fields are “reserved”; any can be overwritten by the user.
No metadata fields are absolutely required. The metadata validation function is user-customizable. The default validation function behaves the same as previous versions of bluesky, but it is no longer manditory.
The signature of
RunEnginehas changed. The
logbookargument is now keyword-only, and there is a new keyword-only argument,
md_validator. See docstring for details.
configuremethod on readable objects now takes a single optional argument, a dictionary that the object can use to configure itself however it sees fit. The
configuremethod always has a new return value, a tuple of dicts describing its old and new states:
old, new = obj.configure(state)
callbacks.broker.post_run API and docstring brought into agreement. The API is change to expect a callable with signature
foo(doc_name, doc)rather than
a callable which takes a document (as documented)
an object with
stopmethods (as implemented).
If classes derived from
CallbackBaseare being used this will not not have any effect on user code.