ophyd-async 0.11__tar.gz → 0.12.1__tar.gz

{ophyd_async-0.11 → ophyd_async-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ophyd-async
-Version: 0.11
+Version: 0.12.1
 Summary: Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango
 Author-email: Tom Cobb <tom.cobb@diamond.ac.uk>
 License: BSD 3-Clause License
@@ -48,6 +48,7 @@ Requires-Dist: pyyaml
 Requires-Dist: colorlog
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pydantic-numpy
+Requires-Dist: stamina>=23.1.0
 Provides-Extra: sim
 Requires-Dist: h5py; extra == "sim"
 Provides-Extra: ca
@@ -120,7 +121,7 @@ The main differences from ophyd sync are:
 - Support for [EPICS][] PVA and [Tango][] as well as the traditional EPICS CA
 - Better library support for splitting the logic from the hardware interface to avoid complex class heirarchies
 
-It was written with the aim of implementing flyscanning in a generic and extensible way with highly customizable devices like PandABox and the Delta Tau PMAC products. Using async code makes it possible to do the "put 3 PVs in parallel, then get from another PV" logic that is common in flyscanning without the performance and complexity overhead of multiple threads.
+It was written with the aim of implementing fly scanning in a generic and extensible way with highly customizable devices like PandABox and the Delta Tau PMAC products. Using async code makes it possible to do the "put 3 PVs in parallel, then get from another PV" logic that is common in fly scanning without the performance and complexity overhead of multiple threads.
 
 Devices from both ophyd sync and ophyd-async can be used in the same RunEngine and even in the same scan. This allows a per-device migration where devices are reimplemented in ophyd-async one by one.
 

{ophyd_async-0.11 → ophyd_async-0.12.1}/README.md

@@ -23,7 +23,7 @@ The main differences from ophyd sync are:
 - Support for [EPICS][] PVA and [Tango][] as well as the traditional EPICS CA
 - Better library support for splitting the logic from the hardware interface to avoid complex class heirarchies
 
-It was written with the aim of implementing flyscanning in a generic and extensible way with highly customizable devices like PandABox and the Delta Tau PMAC products. Using async code makes it possible to do the "put 3 PVs in parallel, then get from another PV" logic that is common in flyscanning without the performance and complexity overhead of multiple threads.
+It was written with the aim of implementing fly scanning in a generic and extensible way with highly customizable devices like PandABox and the Delta Tau PMAC products. Using async code makes it possible to do the "put 3 PVs in parallel, then get from another PV" logic that is common in fly scanning without the performance and complexity overhead of multiple threads.
 
 Devices from both ophyd sync and ophyd-async can be used in the same RunEngine and even in the same scan. This allows a per-device migration where devices are reimplemented in ophyd-async one by one.
 

{ophyd_async-0.11 → ophyd_async-0.12.1}/docs/conf.py

@@ -204,6 +204,7 @@ pygments_style = "sphinx"
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "bluesky": ("https://blueskyproject.io/bluesky/main", None),
+    "scanspec": ("https://blueskyproject.io/scanspec/main", None),
     "numpy": ("https://numpy.org/devdocs/", None),
     "databroker": ("https://blueskyproject.io/databroker/", None),
     "event-model": ("https://blueskyproject.io/event-model/main", None),

{ophyd_async-0.11 → ophyd_async-0.12.1}/docs/explanations/decisions/0007-subpackage-structure.md

@@ -14,7 +14,7 @@ Accepted
 - `ophyd_async.epics`: Epics specific signals and devices
 - `ophyd_async.tango`: Tango specific signals and devices
 - `ophyd_async.fastcs`: FastCS (EPICS or Tango) devices like PandA
-- `ophyd_async.planstubs`: Plan stubs for various flyscan functionality
+- `ophyd_async.planstubs`: Plan stubs for various fly scan functionality
 - `ophyd_async.sim`: Simulated devices for demos and tests
 
 This ADR proposes a public sub-package structure. The internal private structure should be flat, but can change according to the number of classes in a public package.

{ophyd_async-0.11 → ophyd_async-0.12.1}/docs/explanations/design-goals.md

@@ -4,7 +4,7 @@ Ophyd-async was designed to be a library for asynchronously interfacing with har
 
 ## Asynchronous Signal access
 
-A fundamental part of ophyd-async is [](#asyncio). This allows lightweight and deterministic control of multiple signals, making it possible to do the "put 2 PVs in parallel, then get from another PV" logic that is common in flyscanning without the performance and complexity overhead of multiple threads.
+A fundamental part of ophyd-async is [](#asyncio). This allows lightweight and deterministic control of multiple signals, making it possible to do the "put 2 PVs in parallel, then get from another PV" logic that is common in fly scanning without the performance and complexity overhead of multiple threads.
 
 For instance, the threaded version of the above looks something like this:
 ```python
@@ -49,17 +49,17 @@ As well as the tradition EPICS Channel Access, ophyd-async was written to allow
 
 For highly customizable devices like [PandABox](https://quantumdetectors.com/products/pandabox) there are often different pieces of logic that can talk to the same underlying hardware interface. The Devices in ophyd-async are structured so that the logic and interface can be split, and thus can be cleanly organized via composition rather than inheritance. 
 
-## Ease the implementation of flyscanning
+## Ease the implementation of fly scanning
 
-One of the major drivers for ophyd-async was to ease the implementation of flyscanning. A library of flyscanning helpers is being developed to aid such strategies as:
+One of the major drivers for ophyd-async was to ease the implementation of fly scanning. A library of fly scanning helpers is being developed to aid such strategies as:
 - Definition of scan paths via [ScanSpec](https://github.com/dls-controls/scanspec)
 - PVT Trajectory scanning in [Delta Tau motion controllers](https://github.com/dls-controls/pmac)
 - Position compare and capture using a [PandABox](https://quantumdetectors.com/products/pandabox)
 
-These strategies will be ported from DLS's previous flyscanning software [Malcolm](https://github.com/dls-controls/pymalcolm) and improved to take advantage of the flexibility of bluesky's plan definitions.
+These strategies will be ported from DLS's previous fly scanning software [Malcolm](https://github.com/dls-controls/pymalcolm) and improved to take advantage of the flexibility of bluesky's plan definitions.
 
 ```{seealso}
-The documents on flyscanning in the [bluesky cookbook](http://blueskyproject.io/bluesky-cookbook/glossary/flyscanning.html)
+[](../explanations/fly-scanning.md)
 ```
 
 ## Parity and interoperativity with ophyd sync

ophyd_async-0.12.1/docs/explanations/fly-scanning.md

@@ -0,0 +1,97 @@
+# What is the difference between step and fly scanning
+
+A scan is defined as actuating some change in zero or more Devices, then collecting data from zero or more detectors to observe that change. Some examples are:
+- moving a motorized stage with a sample on it, and observing its interaction with the X-ray beam on a pair of detectors simultaneously
+- taking a series of time resolved detector frames to observe the degredation of a sample
+- changing the temperature of the sample and observing it with a detector
+
+The actuators and detectors in a scan are typically different devices, although many actuators allow the current readback position to be read, so will also be used as a source of data during a scan.
+
+We can classify these data collections into two broad categories: step scanning, and fly scanning.
+
+* Step scanning: The system performs a sequence of discrete operations: actuate a change, settle, acquire data, repeat. This ensures well-defined data points but may result in longer total acquisition times. Bluesky plans specify this type of measurement through devices' [Movable](#bluesky.protocols.Movable), [Triggerable](#bluesky.protocols.Triggerable) and [Readable](#bluesky.protocols.Readable) protocols.
+
+* Fly scanning: Short for "on-the-fly scanning," this method involves kicking off the actuation and detection processes simultaneously, with some form of synchronization that allows the data to be correlated after the scan. This effectively hands over some degree of control to the hardware, with bluesky supervising the progress it is making without being in the loop. The benefits are typically faster scans and smoother coverage of the scanned domain, but it adds complexity in the supervision and synchronization of concurrent processes. Devices capable of this mode implement the [Preparable](#bluesky.protocols.Preparable), [Flyable](#bluesky.protocols.Flyable) and [Collectable](#bluesky.protocols.Collectable) protocols.
+
+Filewriting detectors additionally implement [WritesStreamAssets](#bluesky.protocols.WritesStreamAssets) to report the data written to disk during the scan, either at each data point in a step scan, or periodically during a fly scan.
+
+```{seealso}
+[](./plan-stubs.md) for more information on what plan stubs are available that call these protocols
+```
+## Scan frames and collection windows
+
+Consider some trajectory in 2D space:
+
+![A fly scan trajectory with collection windows containing frames](../images/fly_scan_collection_windows_and_frames.svg)
+
+Along the fly scan trajectory we define a discrete sequence of (typically disjoint rather than adjacent) collection windows,
+which are spatial intervals where a coherent block of data is acquired.
+The data collection block is the scan frame, defined as [a vector of lower, mid and upper points in scan space](inv:scanspec#frame_).
+Scan frames map directly to Bluesky [Events](inv:event-model#event), and typically corresponds to a single detector exposure, though they may be composed of multiple detector frames.
+
+## Synchronisation mechanisms
+
+A fly scan must define the start of each collection window and a mechanism for the acquisition of frames within those windows.
+Various mechanisms can be used, depending on the available hardware and experimental requirements. Not all combinations of collection window and scan frame triggers provide useful results, so some examples are given below.
+
+### Collection window triggers
+
+* Software trigger: The control software signals the start of the next window. For example, a plan kicks off a linear motor move, and starts a free-running detector when it expects the motor to reach a desired constant velocity.
+* Time trigger: A window opens at predefined time intervals (this could be a software or a hardware trigger e.g. from a PandA box).
+* Readback trigger: A hardware trigger sent when a signal from a sensor or encoder value is positively evaluated through some position compare logic.
+* Setpoint trigger: The same control signal sent to some device (e.g. a sample environment controller) also triggering the start of the collection window.
+
+### Scan frame triggers
+
+* Internal device trigger: The detector itself generates internal triggers based on its configuration.
+* Time trigger: Hardware triggers sent out at regularly spaced intervals in time.
+* Readback trigger: Same as for collection windows readback triggers.
+* Setpoint trigger: Same as for collection windows setpoint triggers.
+
+When a hardware trigger is sent to a detector, it can either be edge triggered (start a frame of a fixed duration on rising edge of trigger) or level triggered (start a frame on rising edge of trigger, stop the frame on falling edge).
+
+## Examples
+
+With all this in mind, let us consider typical fly scanning setups given a motor and a detector.
+
+### Software collection window with internal triggers
+
+The simplest form of fly scanning uses software synchronisation for opening a collection window, and letting a detector trigger itself internally.
+We effectively tell the devices to "go" at the same time, relying on timestamps to match up the data. The strategy may involve
+
+* Calculating the motor run-up distance and move to the start, setting up the detector to take the right number of frames,
+* Starting the motor moving to its end point and waiting for the amount of time it takes to accelerate
+* Starting the detector
+* Waiting until the detector has finished taking frames and the motor has stopped moving
+
+This process would produce two data stream: a "monitor" stream of timestamped motor readback positions at the control system update rate;
+and a "primary" stream of detector frames with embedded timestamps when they were received by the control point.
+
+### Software collection window with time triggers
+
+If we introduce a PandA box into the system we can trigger the collection window as above, but let the PandA produce time triggers for the detector.
+The strategy is similar:
+
+* Calculate motor run-up distance and move to the start, setting the detector into triggered mode and PandA to send the right number of triggers
+* Start the motor moving to its end point and wait for the amount of time it takes to accelerate
+* Start the PandA sending triggers
+* Wait until the PandA, detector and motor have finished
+
+The data streams produced are a "monitor" stream of timestamped motor readback positions at the control system update rate;
+and a "primary" stream of PandA captured timestamps and detector frames. If the motor happens to be plugged into the PandA
+then we can dispense with the monitor stream as the motor positions can be captured and produced by the PandA.
+
+### Readback collection window with readback triggers
+
+If the motor positions are tracked in the PandA we can use a PCOMP block to trigger both collection windows and frames within.
+This gives the advantage that our detector will trigger at the precise motor positions we expect, but the detector must be able to support level triggering so that it doesn't miss frames if the motor travels faster than expected in a particular frame.
+The strategy and data streams are as in the previous example.
+
+### Readback collection window with time triggers
+
+Similar to above, but if the detector is only capable of edge triggering then we need to give it a constant time period so it doesn't miss frames. We do this by sending regularly spaced triggers from a PandA and capturing the positions that the motors were at.
+
+### Setpoint collection window with setpoint triggers
+
+It is worth mentioning that the Flyer protocol is also used in hardware-triggered step scanning. Though the collection occurs while the scanned axis is stationary,
+the devices are prepared, kicked off, and completed in a similar way to fly scans.

ophyd_async-0.12.1/docs/explanations/plan-stubs.md

@@ -0,0 +1,336 @@
+# What plan stubs will do to Devices
+
+Plan authors will typically compose [plan stubs](inv:bluesky#stub_plans) together to define the behaviour they expect from their Devices. When the plan is executed, the RunEngine will consume the [`Msg` objects](inv:bluesky:std:doc#msg) `yield from` each plan stub as a series of instructions, many of which call methods on the Device. This document lists some commonly used plan stubs, what Devices will do when they are called, and what order they should be called inside the plan.
+
+```{seealso}
+[](./fly-scanning.md) for more information on the difference between step scans (typically software driven) and flyscans (typically hardware driven)
+```
+
+## Plan stubs
+
+### [`bps.stage`](#bluesky.plan_stubs.stage) and [`bps.unstage`](#bluesky.plan_stubs.unstage)
+
+These are typically the first and last Messages in the plan:
+- `stage` gets the Device into an idle state then makes it ready for data collection:
+  - For Devices that read from Signals this will start monitoring those Signals
+  - For detectors that write to a resource (e.g. an HDF file) this will indicate that any captured data (e.g. a detector frame) should be stored in a fresh resource
+- `unstage` returns the Device to an idle state:
+  - For Devices that read from Signals this will stop monitoring those Signals
+  - For detectors that write to a resource this will close that resource
+
+It is recommended that the [`bpp.stage_decorator`](#bluesky.preprocessors.stage_decorator) is applied to the plan to yield these Messages as they do the appropriate error handling.
+
+### [`bps.open_run`](#bluesky.plan_stubs.open_run) and [`bps.close_run`](#bluesky.plan_stubs.close_run)
+
+These are typically the second and second last Messages in the plan:
+- `open_run` indicates to downstream consumers the start of a data collection
+   - For detectors this may be used by specific implentations of `PathProvider` to calculate a new filename to write into
+- `close_run` indicates the end of a data collection
+
+It is recommended that the [`bpp.run_decorator`](#bluesky.preprocessors.run_decorator) is applied to the plan to yield these Messages as they do the appropriate error handling. It should be placed after the `stage_decorator`.
+
+### [`bps.prepare`](#bluesky.plan_stubs.prepare)
+
+Prepares the device for a `trigger` or `kickoff`, after `stage` and `open_run`:
+- For detectors this will set parameters on the hardware such as exposure time and number of frames. If hardware triggering is requested it will also arm the detector so it is ready to receive those triggers.
+- For motors this will move to the run up position and setup the requested motion velocity or trajectory.
+
+### [`bps.abs_set`](#bluesky.plan_stubs.abs_set) or [`bps.mv`](#bluesky.plan_stubs.mv)
+
+Set the device to a target setpoint:
+- For motors, `bps.mv` will move the motor to the desired position, returning when it is complete and erroring if it fails to move. **`bps.abs_set`, however, does not wait for completion by default unless the `wait` option is explicitly set to `True`.**
+
+### [`bps.trigger`](#bluesky.plan_stubs.trigger)
+
+Ask the device to trigger a data collection:
+- For detectors this will take a single exposure. 
+- For motors this will do nothing as the readback position is always valid.
+
+### [`bps.read`](#bluesky.plan_stubs.read)
+
+Collect the data from a device after `trigger`:
+- For detectors that write to a resource this will be a reference to the data written, for other detectors this will be the actual data
+- For motors this is the readback value
+
+
+### [`bps.kickoff`](#bluesky.plan_stubs.kickoff)
+
+Begin a flyscan:
+- For motors this will start motion and return once the motor has completed its run up and is moving at the desired velocity
+- For detectors prepared for software triggering this will start the acquisition
+
+```{note}
+The plan should ensure that `kickoff` on the motors has finished before `kickoff` on the detectors in started so that software triggered detectors don't start too early. Hardware triggered detectors will already be armed from `prepare`.
+```
+
+### [`bps.complete`](#bluesky.plan_stubs.collect) and [`bps.collect`](#bluesky.plan_stubs.collect)
+
+Wait for flyscanning to be done, collecting data from detectors periodically while that happens:
+- `complete` waits for a flyscan to be done:
+  - For motors this will wait until motion including ramp down is complete
+  - For detectors this will wait until the requested number of frames has been written
+- `collect` collects the data that has been written so far by a detector during a flyscan.
+
+Typically called via [`bps.collect_while_completing`](#bluesky.plan_stubs.collect_while_completing), after `kickoff`.
+
+## Ordering
+
+Plan stubs can be mixed together to form arbitrary plans, but there are certain patterns that are common in specific categories of plan. This section lists the ordering of these stubs for step scans (typically software driven), fly scans (typically hardware driven), and scans that nest a fly scan within a step scan.
+
+### Pure step scan
+
+After `stage` and `open_run`, `prepare` can be called to set up detectors for a given exposure time if this has been specified in the plan. The inner loop `set`s motors, then `trigger`s and `read`s detectors for each point. Finally `close_run` and `unstage` do the cleanup.
+
+::::{tab-set}
+:sync-group: diagram-code
+
+:::{tab-item} Diagram
+:sync: diagram
+
+```{mermaid}
+:config: { "theme": "neutral" }
+:align: center
+flowchart TD
+    stage["stage dets, motors"] --> open_run
+    open_run --> prepare["(opt) prepare dets"]
+    prepare --> set["set motors"]
+    set --> trigger["trigger dets"]
+    trigger --> read["read dets, motors"]
+    read --> set
+    read --> close_run
+    close_run --> unstage["unstage dets, motors"]
+
+```
+:::
+
+:::{tab-item} Code
+:sync: code
+
+```python
+@stage_decorator([detector, motor])
+@run_decorator()
+def pure_step(positions: Sequence[float], exposure_time: float | None) -> MsgGenerator:
+    if exposure_time is not None:
+        yield from bps.prepare(detector, TriggerInfo(livetime=exposure_time), wait=True)
+    for position in positions:
+        yield from bps.abs_set(motor, position, wait=True)
+        yield from bps.trigger_and_read(detector, motor)
+```
+
+```{seealso}
+This code is just to aid understanding, normally you would call [](#bluesky.plans.scan) in production
+```
+:::
+
+::::
+
+
+(pure-fly-scan)=
+### Pure fly scan
+
+After `stage` and `open_run`, `prepare` sets up detectors for hardware triggering and motors for a trajectory and `kickoff` starts the prepared motion. Then `complete` is called on motors and detectors. While this is in progress the detectors will be `collect`ed repeatedly. Finally `close_run` and `unstage` do the cleanup.
+
+::::{tab-set}
+:sync-group: diagram-code
+
+:::{tab-item} Diagram
+:sync: diagram
+
+```{mermaid}
+:config: { "theme": "neutral" }
+:align: center
+flowchart TD
+    stage["stage dets, motors"] --> open_run
+    open_run --> prepare["prepare dets, motors"]
+    prepare --> kickoff["kickoff dets, motors"]
+    kickoff --> complete["complete dets, motors"]
+    complete --> collect["collect dets"]
+    collect --> collect
+    collect ----> close_run
+    close_run --> unstage["unstage dets, motors"]
+```
+:::
+
+:::{tab-item} Code
+:sync: code
+
+```python
+@stage_decorator([detector, motor])
+@run_decorator()
+def pure_fly(
+    start_position: float,
+    end_position: float,
+    num_exposures: float,
+    exposure_time: float,
+    readout_time: float,
+) -> MsgGenerator:
+    yield from bps.prepare(
+        detector,
+        TriggerInfo(
+            livetime=exposure_time,
+            deadtime=readout_time,
+            number_of_events=num_exposures,
+        ),
+    )
+    yield from bps.prepare(
+        motor,
+        FlyMotorInfo(
+            start_position=start_position,
+            end_position=end_position,
+            time_for_move=(exposure_time + readout_time) * num_exposures,
+        ),
+    )
+    yield from bps.wait()
+    yield from bps.kickoff_all(motor)
+    yield from bps.kickoff_all(detector)
+    yield from bps.collect_while_completing(
+        flyers=[motor],
+        detectors=[detector],
+        flush_period=0.5,
+    )
+```
+
+```{seealso}
+This code is to aid understanding rather than for copying. This will be documented further in <https://github.com/bluesky/ophyd-async/issues/939>
+```
+:::
+
+::::
+
+
+### Fly scan nested within a step scan
+
+After `stage` and `open_run` the detectors are `prepare`d for the entire scan. The inner loop `set`s the slow (software) motors to each point, followed by the hardware driven section of the scan. Just like the [](#pure-fly-scan), this consists of `prepare`, then `kickoff`, then `complete` of the fast (hardware) motors, `collect`ing from the detectors repeatedly until they are finished. Finally `close_run` and `unstage` do the cleanup.
+
+::::{tab-set}
+:sync-group: diagram-code
+
+:::{tab-item} Diagram
+:sync: diagram
+
+```{mermaid}
+:config: { "theme": "neutral" }
+:align: center
+flowchart TD
+    stage["stage dets, motors"] --> open_run
+    open_run --> prepare_d["prepare dets"]
+    prepare_d --> set["set slow motors"]
+    set --> prepare_m["prepare fast motors"]
+    prepare_m --> kickoff["kickoff dets, fast motors"]
+    kickoff --> complete["complete dets, fast motors"]
+    complete --> collect["collect dets"]
+    collect --> collect
+    collect --> set
+    collect ----> close_run
+    close_run --> unstage["unstage dets, motors"]
+```
+:::
+
+:::{tab-item} Code
+:sync: code
+
+```python
+@stage_decorator([detector, column_motor, row_motor])
+@run_decorator()
+def fly_inside_step(
+    columns: Sequence[float],
+    row_start: float,
+    row_end: float,
+    exposures_per_row: int,
+    exposure_time: float,
+    readout_time: float,
+) -> MsgGenerator:
+    yield from bps.prepare(
+        detector,
+        TriggerInfo(
+            livetime=exposure_time,
+            deadtime=readout_time,
+            number_of_events=exposures_per_row * len(columns),
+        ),
+    )
+    for column in columns:    
+        yield from bps.abs_set(column_motor, column)
+        yield from bps.prepare(
+            row_motor,
+            FlyMotorInfo(
+                start_position=row_start,
+                end_position=row_end,
+                time_for_move=(exposure_time + readout_time) * exposures_per_row,
+            ),
+        )
+        yield from bps.wait()
+        yield from bps.kickoff_all(row_motor)
+        yield from bps.kickoff_all(detector)
+        yield from bps.collect_while_completing(
+            flyers=[row_motor],
+            detectors=[detector],
+            flush_period=0.5,
+        )
+```
+
+```{seealso}
+This code is to aid understanding rather than for copying. This will be documented further in <https://github.com/bluesky/ophyd-async/issues/939>
+```
+:::
+
+::::
+
+
+
+## Conclusion
+
+The following table summarized what each plan stub does to each class of device:
+
+
+```{list-table}
+:header-rows: 1
+
+* - Verb
+  - Behavior if Motor
+  - Behavior if Detector
+  - Step / Fly
+* - `stage`
+  - Starts monitoring Signals
+  - Ensures idle; flags next frame should go in a new resource
+  - Both
+* - `unstage`
+  - Stops monitoring signals
+  - Closes resources
+  - Both
+* - `open_run`
+  - No effect
+  - May compute new resource ID for writing
+  - Both
+* - `close_run`
+  - No effect
+  - Signals the end of data capture
+  - Both
+* - `prepare`
+  - Moves to run-up position; sets velocity/trajectory
+  - Sets acquisition parameters; arms hardware-triggered detectors
+  - Both
+* - `abs_set` / `mv`
+  - Moves motor to a target position
+  - N/A
+  - Step
+* - `trigger`
+  - N/A
+  - Captures a single exposure
+  - Step
+* - `read`
+  - Reads current position
+  - Reads triggered data
+  - Step
+* - `kickoff`
+  - Starts motion and returns once stable velocity is reached
+  - Starts acquisition (software-triggered); hardware-triggered detectors already armed in `prepare`
+  - Fly
+* - `complete`
+  - Waits for motion (including ramp down) to finish
+  - Waits for acquisition to finish (e.g. number of frames)
+  - Fly
+* - `collect`
+  - N/A
+  - Retrieves data already acquired during the scan
+  - Fly
+```

{ophyd_async-0.11 → ophyd_async-0.12.1}/docs/how-to/choose-right-baseclass.md

@@ -11,8 +11,8 @@ When writing a new Device there are several base classes to choose from that wil
 There are some utility baseclasses that allow you to create a Device pre-populated with the right verbs to work in bluesky plans:
 
 - [](#StandardReadable) allows you to compose the values of child Signals and Devices together so that you can `read()` the Device during a step scan.
-- [](#StandardDetector) allows file-writing detectors to be used within both step and flyscans, reporting periodic references to the data that has been written so far. An instance of a [](#DetectorController) and a [](#DetectorWriter) are required to provide this functionality.
-- [](#StandardFlyer) allows actuators (like a motor controller) to be used within a flyscan. Implementing a [](#FlyerController) is required to provide this functionality.
+- [](#StandardDetector) allows file-writing detectors to be used within both step and fly scans, reporting periodic references to the data that has been written so far. An instance of a [](#DetectorController) and a [](#DetectorWriter) are required to provide this functionality.
+- [](#StandardFlyer) allows actuators (like a motor controller) to be used within a fly scan. Implementing a [](#FlyerController) is required to provide this functionality.
 
 ## Adding verbs via protocols
 

{ophyd_async-0.11 → ophyd_async-0.12.1}/pyproject.toml

@@ -20,6 +20,7 @@ dependencies = [
     "colorlog",
     "pydantic>=2.0",
     "pydantic-numpy",
+    "stamina>=23.1.0"
 ]
 dynamic = ["version"]
 license.file = "LICENSE"
@@ -101,7 +102,7 @@ markers = [
 ]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
-timeout = 0.5
+timeout = 0.75
 [tool.coverage.run]
 data_file = "/tmp/ophyd_async.coverage"
 

{ophyd_async-0.11 → ophyd_async-0.12.1}/src/ophyd_async/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.11'
-__version_tuple__ = version_tuple = (0, 11)
+__version__ = version = '0.12.1'
+__version_tuple__ = version_tuple = (0, 12, 1)

{ophyd_async-0.11 → ophyd_async-0.12.1}/src/ophyd_async/core/_flyer.py

@@ -17,15 +17,15 @@ class FlyerController(ABC, Generic[T]):
 
     @abstractmethod
     async def prepare(self, value: T) -> Any:
-        """Move to the start of the flyscan."""
+        """Move to the start of the fly scan."""
 
     @abstractmethod
     async def kickoff(self):
-        """Start the flyscan."""
+        """Start the fly scan."""
 
     @abstractmethod
     async def complete(self):
-        """Block until the flyscan is done."""
+        """Block until the fly scan is done."""
 
     @abstractmethod
     async def stop(self):
@@ -101,7 +101,7 @@ class StandardFlyer(
         return AsyncStatus(self._prepare(value))
 
     async def _prepare(self, value: T) -> None:
-        # Move to start and setup the flyscan
+        # Move to start and setup the fly scan
         await self._trigger_logic.prepare(value)
 
     @AsyncStatus.wrap

{ophyd_async-0.11 → ophyd_async-0.12.1}/src/ophyd_async/core/_hdf_dataset.py

@@ -1,6 +1,4 @@
 from collections.abc import Iterator
-from pathlib import Path
-from urllib.parse import urlunparse
 
 from bluesky.protocols import StreamAsset
 from event_model import (  # type: ignore
@@ -48,22 +46,11 @@ class HDFDocumentComposer:
 
     def __init__(
         self,
-        full_file_name: Path,
+        file_uri: str,
         datasets: list[HDFDatasetDescription],
-        hostname: str = "localhost",
     ) -> None:
         self._last_emitted = 0
-        self._hostname = hostname
-        uri = urlunparse(
-            (
-                "file",
-                self._hostname,
-                str(full_file_name.absolute()),
-                "",
-                "",
-                None,
-            )
-        )
+        uri = file_uri
         bundler_composer = ComposeStreamResource()
         self._bundles: list[ComposeStreamResourceBundle] = [
             bundler_composer(