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.
Previously, the ~bluesky.RunEngine
had been repeatedly starting and stopping the asyncio event loop in ~bluesky.RunEngine.__call__
, ~bluesky.RunEngine.request_pause
, ~bluesky.RunEngine.stop
, in ~bluesky.RunEngine.abort
, ~bluesky.RunEngine.halt
, and ~bluesky.RunEngine.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 ~bluesky.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
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.
We need to block the main thread in ~bluesky.RunEngine.__call__
(and ~bluesky.RunEngine.resume
) until the user supplied plan is complete. Previously, we would do this by calling self.loop.run_forever()
to start the asyncio event loop. We would then stop the event loop an the bottom of ~bluesky.RunEngine._run
and in ~bluesky.RunEngine.request_pause
to un-block the main thread and return control to the user terminal. Now we must find an alternative way to achieve this effect.
There is a a threading.Event
on the ~bluesky.RunEngine
that will be set when the task for ~bluesky.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 ~bluesky.RunEngine
so we added a hook, set at init time, for a function that passed the threading.Event
and is responsible for blocking until it is set. This function can do other things (such as run the Qt event loop) during that time. The required signature is :
def blocking_func(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.
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 asyncio.wait
, we now expect that the iterable passed in is callables with the signature:
def fut_fac() -> awaitable:
'This must work multiple times'
- Generalized
~bluesky.plans.list_scan
to work on any number of motors, not just one. In v1.2.0,~bluesky.plans.scan
was generalized in the same way. - Added
~bluesky.plans.list_grid_scan
. - Raise a more helpful error message if the
num
parameter given to ~bluesky.plans.scan is not a whole number, as can happen ifnum
is 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
obj.read()
returnsNone
instead of the expected dict. - If the user tries to start a
~bluesky.callbacks.zmq.RemoteDispatcher
after it has been stopped, raise a more helpful error message.
- The
state
attribute of theRunEngine
is 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.
This release removes the dependency on an old version of the jsonschema
library and requires the latest version of the event-model
library.
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,~bluesky.set_handler
, addresses common cases such as directing the log output to a file. - The
bluesky-0MQ-proxy
script now supports a-v, --verbose
option, 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.Publisher
can 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_id
key in the RunStart document. The source of thescan_id
is now pluggable via a new parameter,scan_id_source
. Seerun_engine_api
for details. - The convenience function,
bluesky.utils.ts_msg_hook
accepts new parameterfile
for 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.RemoteDispatcher
has been changed in a non-backward-compatible way. The parameters for filtering messages byhostname
,pid
, andrun_engine_id
have been replaced by one new parameter,prefix
. - The default value of
RunEngine.verbose
is nowTrue
, meaning that theRunEngine.log
is not disabled by default.
- The
bluesky.callbacks.zmq.Publisher
accepts 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
~bluesky.callbacks.mpl_plotting.LiveGrid
unusable.
- Added ability to control 'sense' of
~bluesky.callbacks.mpl_plotting.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.
- Promoted the inner function from
~bluesky.plan_stubs.one_nd_step
to a top-level planbluesky.plan_stubs.move_per_step
. - Added flag to
~bluesky.plans.ramp_plan
to control if a data point is taken before the ramp starts.
- Ensure order stability in
~bluesky.magics.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
%wa
magic 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,
install_suspender
andremove_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_managers
that 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:
~bluesky.plans.x2x_scan
,~bluesky.plans.spiral_square_plan
, and~bluesky.plans.rel_spiral_square_plan
. - Add convenience methods for reviewing the available commands,
~bluesky.run_engine.RunEngine.commands
and~bluesky.run_engine.RunEngine.print_command_registry
. - Add a
crossings
attribute toPeakStats
.
- 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
LiveFit
that should have produced a warning produced an error instead.
- User-defined callbacks subscribed to the RunEngine
'all'
stream must accept documents with names'resource'
,'datum'
and'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.positioners
andBlueskyMagics.detectors
, the magics now scrape the user namespace for objects that implement the_ophyd_labels_
interface. Seemagics
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. - Extend
.scan
and.rel_scan
to handle multiple motors, rendering.inner_product_scan
andrelative_inner_product_scan
redundant. - A new plan stub,
~bluesky.plan_stubs.repeat
, repeats another plan N times with optional interleaved delays --- a kind of customizable version of~bluesky.plans.count
. - Better validation of user-defined
per_step
functions and more informative error messages to match.
- Fix axes orientation in
.LiveRaster
. - Make
.BestEffortCallback
display 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
.BestEffortCallback
to 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.
- The
~bluesky.plan_stubs.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
~bluesky.run_engine.RunEngine
,'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. - Add
~bluesky.utils.install_kicker
, which dispatches automatically to~bluesky.utils.install_qt_kicker
or~bluesky.utils.install_nb_kicker
depending on the current matplotlib backend.
- Fix the hint for
~bluesky.plans.inner_product_scan
, which previously used a default hint that was incorrect.
- In
~bluesky.plans.tune_centroid
, change the meaning of thestep_factor
parameter 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. - The
~bluesky.preprocessors.SupplementalData
preprocessor inserts its instructions in a more logical order: first baseline readings, then monitors, then flyers. Previously, the order was reversed. - The suspender
~bluesky.suspenders.SuspendInBand
has been renamed to~bluesky.suspenders.SuspendWhenOutsideBand
to 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. - The suspender
~bluesky.suspenders.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.
~bluesky.plan_stubs.mv
and~bluesky.plan_stubs.mvr
now works on pseudopositioners.~bluesky.preprocessors.reset_positions_wrapper
now works on pseudopositioners.- Plans given an empty detectors list, such as
count([])
, no longer break the~bluesky.callbacks.best_effort.BestEffortCallback
.
This is the last release before 1.0.0. It contains major restructurings and general clean-up.
The
bluesky.plans
module has been split intobluesky.plans
--- plans that create a run, such ascount
andscan
bluesky.preprocessors
--- plans that take in other plans and motify them, such asbaseline_wrapper
bluesky.plan_stubs
--- small plans meant as convenient building blocks for creating custom plans, such astrigger_and_read
bluesky.object_plans
andbluesky.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
RunEngineInterrupted
exception when interrupted (e.g. paused). The optional argumentraise_if_interrupted
has been removed. - The module
bluesky.callbacks.scientific
has been removed. PeakStats
has been moved tobluesky.callbacks.fitting
, andplot_peak_stats
has been moved to bluesky.callbacks.mpl_plotting.- The synthetic 'hardware' objects in
bluesky.examples
have been relocated to ophyd (bluesky's sister package) and aggressively refactored to be more closely aligned with the behavior of real hardware. TheReader
andMover
classes have been removed in favor ofSynSignal
,SynPeriodicSignal
,SynAxis
,SynSignalWithRegistry
.
- Add
stub_wrapper
andstub_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. - Add
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.
- Add
contingency_wrapper
andcontingency_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
RunEngine.pause_msg
.
- Fix ordering of dimensions in
grid_scan
hints. - 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.
- Correctly mark
exit_status
field in RunStop metadata based on which termination method was called (abort, stop, halt). LiveFitPlot
handles updates more carefully.
- The
bluesky.callbacks
package 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.
- Fix critical
baseline_wrapper
bug. - Make
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.spec_api
andbluesky.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.
No
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())
do:
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
ct
andascan
. They were ignored by their counterpartscount
andscan
, as well as user-defined plans. This was not desirable!This scheme has been replaced by the
supplemental data <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
ct
andascan
automatically set up a suitable table and a plot, while their "standard" vanilla counterparts,bluesky.plans.count
andbluesky.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
Use
bec.disable()
andbec.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
Inside
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 likepeaks.com['ccd_stats1_total']
.
- The functions and classes in the module
bluesky.callbacks.broker
require a instance ofBroker
to be passed in as an argument. They used to default to the 'singleton' instance viafrom databroker import db
, which is now a deprecated usage in databroker. - The plan preprocessors
configure_count_time_wrapper
andconfigure_count_time_decorator
were moved tobluesky.plans
frombluesky.spec_api
, reverting a change made in v0.9.0. - The 0MQ pubsub integration classes
Publisher
andRemoteDispatcher
have been overhauled. They have been moved frombluesky.callbacks.zmqpub
andbluesky.callbacks.zmqsub
tobluesky.callbacks.zmq
and their signatures have been changed to match similar utilities in the pydata ecosystem. See the Enhancements section for more information. - The module
bluesky.qt_kicker
has been removed. Its former contents are avaiable inbluesky.utils
. The module was originally deprecated in April 2016, and it has been issuing warnings about this change since. - The plan
bluesky.plans.input
has been renamedbluesky.plans.input_plan
to 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.
- The module
bluesky.plan_tools
has been renamedbluesky.simualtors
. In the new module,bluesky.plan_tools.print_summary
has been renamed :func:`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 (
Count
,Scan
, etc.) have been deprecated and will be removed in a future release. Their documentation has been removed. - The plan context managers (
run_context
,stage_context
, etc.) have been deprecated and will be removed in a future release. They were never documented or widely used. - The method
bluesky.Dispatcher.subscribe
(which is encapsulated intobluesky.RunEngine
and inherited bybluesky.callbacks.zmq.RemoteDispatcher
) has a new signature. The former signature wassubscribe(name, func)
. The new signature issubscribe(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 <progress-bar>
add-on is available. - As addressed above:
- The new
supplemental data <supplemental_data>
feature make it easy to set up "baseline" readings and asynchronous acquisition in a way that applies automatically to all plans. - The new
best-effort callback <best_effort_callback>
sets up automatic terminal output and plots for all plans, including user-defined ones.
- The new
LivePlot
now acceptsx='time'
. It can set t=0 to the UNIX epoch or to the start of the run. It also acceptsx='seq_num'
---a synonym forx=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 tobluesky.plan.mv
. - The 0MQ pubsub integration classes
bluesky.callbacks.zmq.Publisher
and :class:`bluesky.callbacks.zmq.RemoteDispatcher have been simplified. A new classbluesky.callbacks.zmq.Proxy
and command-line utilitybluesky-0MQ-proxy
has 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 havea new hints attribute <hints>
. Its content may change or expand in future releases as this new feature is explored. - Some
IPython magics <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.
- The
requirements.txt
failed to declare that bluesky requires matplotlib.
- Moved
configure_count_time_wrapper
andconfigure_count_time_decorator
tobluesky.spec_api
frombluesky.plans
. - The metadata reported by step scans that used to be labeled
num_steps
is now renamednum_points
, generally considered a less ambiguous name. Separately,num_interals
(which one might mistakenly assume is what was meant bynum_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_mutator
so that it properly handles return values. One effect of this fix is thatbaseline_wrapper
properly passed run uids through. - Fix bug in
LiveFit
that broke multivariate fits. - Minor fixes to example detectors.
- A
KeyboardInterrupt
exception captured during a run used to cause the RunEngine to pause. Now it halts instead.
- Nonlinear least-squares minimization callback
LiveFit
withLiveFitPlot
- Added
RunEngine.clear_suspenders()
convenience method. - New
RunEngine.preprocessors
list that modifies all plans passed to the RunEngine. - Added
RunEngine.state_hook
to monitor state changes, akin tomsg_hook
. - Added
pause_for_debug
options tofinalize_wrapper
which 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.
- Added
mv
, a convenient plan for moving multiple devices in parallel. - Added optional
RunEngine.max_depth
to 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
post_run
callback. - 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.
- The flag
RunEngine.ignore_callback_exceptions
now defaults to False. - The plan
complete
, related to fly scans, previously hadwait=True
by default, although its documentation indicated thatFalse
was the default. The code has been changed to match the documentation. Any calls tocomplete
that are expected to be blocking should be updated with the keywordwait=True
. - Completely change the API of
Reader
andMover
, the classes for definding simulated devices. - The bluesky interface now expects the
stop
method on a device to accept an optionalsuccess
argument. - The optional, undocumented
fig
argument toLivePlot
has been deprecated and will be removed in a future release. Anax
argument has been added. Additionally, the axes used byLiveGrid
andLiveScatter
is configurable through a new, optionalax
argument. - 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
fromsignal_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.
- Add
aspect
argument toLiveGrid
. - Add
install_nb_kicker
to get live-updating matplotlib figures in the notebook while the RunEngine is running. - Simulated hardware devices
Reader
andMover
can be easily customized to mock a wider range of behaviors, for testing and demos. - Integrate the SPEC API with mew global state attribute
gs.MONITORS
. - Callbacks that use the databroker accept an optional
Broker
instance as an argument.
- Minor fix in the tilt computation for spiral scans.
- Expost 'tilt' option through SPEC-like API
- The "infinite count" (
ct
withnum=None
) should spawn a LivePlot. finalize_decorator
accepts a callable (e.g., generator function) and does not accept an iterable (e.g., generator instance)- Restore
gs.FLYERS
integration to the SPEC API (accidentally removed).
- The API for the simulated hardware example devices
Reader
andMover
has been changed to make them more general. - Remove
register_mds
metadatastore integration.
- 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.
- Add
monitor_during_wrapper
and corresponding decorator. - Add
stage_wrapper
and corresponding decorator. - Built-in plans return the run uid that they generated.
- Add a new
ramp_plan
for 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.
- Remove the
planify
decorator 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
make_decorator
return 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_read
plan looks for; and a special exception that devices can raise when theirpause
method 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:
inject_md_wrapper
,run_wrapper
,rewindable_wrapper
.
- Fix bug where RunEngine was put in the "running" state, encountered an error before starting the
_run
coroutine, 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.
- The SPEC-style
tw
was not passing its parameters through to the underlyingtweak
plan. - Silenced un-needed suspenders warnings
- Fix bug in separating devices
- Reduce unneeded usage of
bluesky.plans.single_gen
. - Don't emit create/save messages with no reads in between.
- Re-work exception handling in main run engine event loop.
LiveTable
only displays data from one event stream.- Remove used global state attribute
gs.COUNT_TIME
.
- Fix "infinite count",
ct(num=None)
. - 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
ct
implement baseline readings, referring togs.BASELINE_DETS
. - Upon resuming after a deferred pause, clear the deferred pause request.
- Make
bluesky.utils.register_transform
character configurable.
- 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.
- Move
bluesky.scientific_callbacks
tobluesky.callbacks.scientific
andbluesky.broker_callbacks
tobluesky.callbacks.broker
. - Remove
bluesky.register_mds
whose usage can be replaced by:import metadatastore.commands; RE.subscribe_lossless('all', metadatastore.commands.insert)
- In all occurrences, the argument
block_group
has been renamedgroup
for consistency. This affects the 'trigger' and 'set' messages. - The (not widely used)
Center
plan 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
- hscan
- kscan
- lscan
- tscan
- dtscan
- hklscan
- hklmesh
They can be defined in configuration files as desired, and in that location they will be easier to customize.
- The
describe
method on flyers, which returns an iterable of dicts of data keys for one or more descriptors documents, has been renamed todescribe_collect
to avoid confusion withdescribe
on other devices, which returns a dict of data keys for one descriptor document. - An obscure feature in
RunEngine.request_pause
has been removed, which involved removing the optional argumentscallback
andname
.
- Address serious performance problem in
LiveTable
.
- 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
name
, using'primary'
by default. - Record a mapping of device/signal names to ordered data keys in the EventDescriptor.
- Let
LiveRaster
account for "snaked" trajectories.
PeakStats.com
is a scalar, not a single-element array.- Restore Python 3.4 compatibility.
(TO DO)
(TO DO)
(TO DO)
- Removed
RunEngine.persistent_fields
; all fields inRE.md
persist 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
RunEngine
has changed. Thelogbook
argument is now keyword-only, and there is a new keyword-only argument,md_validator
. See docstring for details. - The
configure
method on readable objects now takes a single optional argument, a dictionary that the object can use to configure itself however it sees fit. Theconfigure
method always has a new return value, a tuple of dicts describing its old and new states:old, new = obj.configure(state)
- Removed method
increment_scan_id
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
start
,descriptor
,event
andstop
methods (as implemented).
If classes derived from
CallbackBase
are being used this will not not have any effect on user code.
(TO DO)
(TO DO)
(TO DO)
(TO DO)
Initial release