Annotated default plans

Introduction

This is essentially a copy of https://github.com/bluesky/bluesky/pull/1610, with some stuff for queueserver annotation added.

The typing part should be removed once that PR is merged.

For the motor arguments, the plans expect a list of misc. stuff. To make stuff make sense in our GUI applications, we developed a simple CSV-like comment to put in the argument’s description, for specifying what each argument in the list means.

The comment starts and ends with the -.- string, and between those, it has three CSV row entries, separated by a ‘;’ character, like so:

-.-row one; row two; row three-.-

Row one represents the name of each argument in that list, in sequence. For instance, grid_scan would have the following as their first row: motor,start,stop,num. Meanwhile, list_scan would instead have something like motor,start,stop, since it has no num parameter.

Row two represents the description for each argument, in sequence. It must be the same length as the first row, though any or all elements in there can be empty (,,).

Row three represents the type of each argument, in sequence. As with row two, it must be the same length as the first row, but unlike the second row, it must have all elements be non-empty, even if it’s all just typing.Any.

Plans

Tip

Check the official Bluesky documentation for the original plan descriptions, and other useful information.

sophys.common.plans.annotated_default_plans.count(detectors: Sequence[Readable], num: int | None = 1, delay: float | Sequence[float] | None = None, *, per_shot: Callable[[Sequence[Readable], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Take one or more readings from detectors.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
num (integer, optional) –
number of readings to take; default is 1

If None, capture data until canceled
delay (iterable or scalar, optional) – Time delay in seconds between successive readings; default is 0.
per_shot (callable, optional) –
hook for customizing action of inner loop (messages per step) Expected signature
```
def f(detectors: Iterable[OphydObj]) -> Generator[Msg]:
    ...
```
md (dict, optional) – metadata

Notes

If delay is an iterable, it must have at least num - 1 entries or the plan will raise a ValueError during iteration.

sophys.common.plans.annotated_default_plans.scan(detectors: Sequence[Readable], /, *args, num: int = None, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over one multi-motor trajectory.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
*args –
For one dimension, motor, start, stop. In general:
```
motor1, start1, stop1,
motor2, start2, stop2,
...,
motorN, startN, stopN
```
Motors can be any ‘settable’ object (motor, temp controller, etc.)
num (integer) – number of points
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.relative_inner_product_scan(), bluesky.plans.grid_scan(), bluesky.plans.scan_nd()

sophys.common.plans.annotated_default_plans.rel_scan(detectors: Sequence[Readable], /, *args, num: int = None, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over one multi-motor trajectory relative to current position.

Parameters:

detectors (list) – list of ‘readable’ objects
*args –
For one dimension, motor, start, stop. In general:
```
motor1, start1, stop1,
motor2, start2, start2,
...,
motorN, startN, stopN,
```
Motors can be any ‘settable’ object (motor, temp controller, etc.)
num (integer) – number of points
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.rel_grid_scan(), bluesky.plans.inner_product_scan(), bluesky.plans.scan_nd()

sophys.common.plans.annotated_default_plans.list_scan(detectors: Sequence[Readable], /, *args, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over one or more variables in steps simultaneously (inner product).

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
*args –
For one dimension, motor, [point1, point2, ....]. In general:
```
motor1, [point1, point2, ...],
motor2, [point1, point2, ...],
...,
motorN, [point1, point2, ...]
```
Motors can be any ‘settable’ object (motor, temp controller, etc.)
per_step (callable, optional) – hook for customizing action of inner loop (messages per step) Expected signature: f(detectors, motor, step) -> plan (a generator)
md (dict, optional) – metadata

See also

bluesky.plans.rel_list_scan(), bluesky.plans.list_grid_scan(), bluesky.plans.rel_list_grid_scan()

sophys.common.plans.annotated_default_plans.rel_list_scan(detectors: Sequence[Readable], /, *args, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over one variable in steps relative to current position.

Parameters:

detectors (list) – list of ‘readable’ objects
*args –
For one dimension, motor, [point1, point2, ....]. In general:
```
motor1, [point1, point2, ...],
motor2, [point1, point2, ...],
...,
motorN, [point1, point2, ...]
```
Motors can be any ‘settable’ object (motor, temp controller, etc.) point1, point2 etc are relative to the current location.
motor (object) – any ‘settable’ object (motor, temp controller, etc.)
steps (list) – list of positions relative to current position
per_step (callable, optional) – hook for customizing action of inner loop (messages per step) Expected signature: f(detectors, motor, step)
md (dict, optional) – metadata

See also

bluesky.plans.list_scan(), bluesky.plans.list_grid_scan(), bluesky.plans.rel_list_grid_scan()

sophys.common.plans.annotated_default_plans.list_grid_scan(detectors: Sequence[Readable], /, *args, snake_axes: bool | Sequence[Movable] = False, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over a mesh; each motor is on an independent trajectory.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
args (list) –

patterned like (motor1, position_list1,
motor2, position_list2, motor3, position_list3, ..., motorN, position_listN)

The first motor is the “slowest”, the outer loop. position_list’s are lists of positions, all lists must have the same length. Motors can be any ‘settable’ object (motor, temp controller, etc.).
snake_axes (boolean or iterable, optional) – which axes should be snaked, either False (do not snake any axes), True (snake all axes) or a list of axes to snake. “Snaking” an axis is defined as following snake-like, winding trajectory instead of a simple left-to-right trajectory.The elements of the list are motors that are listed in args. The list must not contain the slowest (first) motor, since it can’t be snaked.
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.rel_list_grid_scan(), bluesky.plans.list_scan(), bluesky.plans.rel_list_scan()

sophys.common.plans.annotated_default_plans.rel_list_grid_scan(detectors: Sequence[Readable], /, *args, snake_axes: bool | Sequence[Movable] = False, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over a mesh; each motor is on an independent trajectory. Each point is relative to the current position.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
args –

patterned like (motor1, position_list1,
motor2, position_list2, motor3, position_list3, ..., motorN, position_listN)

The first motor is the “slowest”, the outer loop. position_list’s are lists of positions, all lists must have the same length. Motors can be any ‘settable’ object (motor, temp controller, etc.).
snake_axes (boolean or Iterable, optional) – which axes should be snaked, either False (do not snake any axes), True (snake all axes) or a list of axes to snake. “Snaking” an axis is defined as following snake-like, winding trajectory instead of a simple left-to-right trajectory.The elements of the list are motors that are listed in args. The list must not contain the slowest (first) motor, since it can’t be snaked.
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.list_grid_scan(), bluesky.plans.list_scan(), bluesky.plans.rel_list_scan()

sophys.common.plans.annotated_default_plans.log_scan(detectors: Sequence[Readable], motor: Movable, start: float, stop: float, num: int | None = 1, *, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over one variable in log-spaced steps.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
motor (object) – any ‘settable’ object (motor, temp controller, etc.)
start (float) – starting position of motor
stop (float) – ending position of motor
num (int) – number of steps
per_step (callable, optional) – hook for customizing action of inner loop (messages per step) Expected signature: f(detectors, motor, step)
md (dict, optional) – metadata

See also

bluesky.plans.rel_log_scan()

sophys.common.plans.annotated_default_plans.rel_log_scan(detectors: Sequence[Readable], motor: Movable, start: float, stop: float, num: int | None = 1, *, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over one variable in log-spaced steps relative to current position.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
motor (object) – any ‘settable’ object (motor, temp controller, etc.)
start (float) – starting position of motor
stop (float) – ending position of motor
num (int) – number of steps
per_step (callable, optional) – hook for customizing action of inner loop (messages per step) Expected signature: f(detectors, motor, step)
md (dict, optional) – metadata

See also

bluesky.plans.log_scan()

sophys.common.plans.annotated_default_plans.grid_scan(detectors: Sequence[Readable], /, *args, snake_axes: bool | Sequence[Movable] = False, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over a mesh; each motor is on an independent trajectory.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
*args –

patterned like (motor1, start1, stop1, num1,
motor2, start2, stop2, num2, motor3, start3, stop3, num3, … motorN, startN, stopN, numN)

The first motor is the “slowest”, the outer loop. For all motors except the first motor, there is a “snake” argument: a boolean indicating whether to following snake-like, winding trajectory or a simple left-to-right trajectory.
snake_axes (boolean or iterable, optional) – which axes should be snaked, either False (do not snake any axes), True (snake all axes) or a list of axes to snake. “Snaking” an axis is defined as following snake-like, winding trajectory instead of a simple left-to-right trajectory. The elements of the list are motors that are listed in args. The list must not contain the slowest (first) motor, since it can’t be snaked.
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.rel_grid_scan(), bluesky.plans.inner_product_scan(), bluesky.plans.scan_nd()

sophys.common.plans.annotated_default_plans.rel_grid_scan(detectors: Sequence[Readable], /, *args, snake_axes: bool | Sequence[Movable] = False, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over a mesh relative to current position.

Parameters:

detectors (list) – list of ‘readable’ objects
*args –

patterned like (motor1, start1, stop1, num1,
motor2, start2, stop2, num2, motor3, start3, stop3, num3, … motorN, startN, stopN, numN)

The first motor is the “slowest”, the outer loop. For all motors except the first motor, there is a “snake” argument: a boolean indicating whether to following snake-like, winding trajectory or a simple left-to-right trajectory.
snake_axes (boolean or iterable, optional) – which axes should be snaked, either False (do not snake any axes), True (snake all axes) or a list of axes to snake. “Snaking” an axis is defined as following snake-like, winding trajectory instead of a simple left-to-right trajectory. The elements of the list are motors that are listed in args. The list must not contain the slowest (first) motor, since it can’t be snaked.
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.relative_inner_product_scan(), bluesky.plans.grid_scan(), bluesky.plans.scan_nd()

sophys.common.plans.annotated_default_plans.scan_nd(detectors: Sequence[Readable], cycler: Cycler, *, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Scan over an arbitrary N-dimensional trajectory.

Parameters:

detectors (list or tuple) –
cycler (Cycler) – cycler.Cycler object mapping movable interfaces to positions
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.inner_product_scan(), bluesky.plans.grid_scan()

Examples

>>> from cycler import cycler
>>> cy = cycler(motor1, [1, 2, 3]) * cycler(motor2, [4, 5, 6])
>>> scan_nd([sensor], cy)

sophys.common.plans.annotated_default_plans.spiral(detectors: Sequence[Readable], x_motor: Movable, y_motor: Movable, x_start: float, y_start: float, x_range: float, y_range: float, dr: float, nth: float, *, dr_y: float | None = None, tilt: float = 0.0, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Spiral scan, centered around (x_start, y_start)

Parameters:

x_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
y_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
x_start (float) – x center
y_start (float) – y center
x_range (float) – x width of spiral
y_range (float) – y width of spiral
dr (float) – Delta radius along the minor axis of the ellipse.
dr_y (float, optional) – Delta radius along the major axis of the ellipse. If None, defaults to dr.
nth (float) – Number of theta steps
tilt (float, optional) – Tilt angle in radians, default 0.0
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.rel_spiral(), bluesky.plans.spiral_fermat(), bluesky.plans.rel_spiral_fermat()

sophys.common.plans.annotated_default_plans.spiral_fermat(detectors: Sequence[Readable], x_motor: Movable, y_motor: Movable, x_start: float, y_start: float, x_range: float, y_range: float, dr: float, factor: float, *, dr_y: float | None = None, tilt: float = 0.0, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Absolute fermat spiral scan, centered around (x_start, y_start)

Parameters:

detectors (list) – list of ‘readable’ objects
x_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
y_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
x_start (float) – x center
y_start (float) – y center
x_range (float) – x width of spiral
y_range (float) – y width of spiral
dr (float) – delta radius
factor (float) – radius gets divided by this
dr_y (float, optional) – Delta radius along the major axis of the ellipse, if not specifed defaults to dr.
tilt (float, optional) – Tilt angle in radians, default 0.0
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.spiral(), bluesky.plans.rel_spiral(), bluesky.plans.rel_spiral_fermat()

sophys.common.plans.annotated_default_plans.spiral_square(detectors: Sequence[Readable], x_motor: Movable, y_motor: Movable, x_center: float, y_center: float, x_range: float, y_range: float, x_num: float, y_num: float, *, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Absolute square spiral scan, centered around (x_center, y_center)

Parameters:

detectors (list) – list of ‘readable’ objects
x_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
y_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
x_center (float) – x center
y_center (float) – y center
x_range (float) – x width of spiral
y_range (float) – y width of spiral
x_num (float) – number of x axis points
y_num (float) – Number of y axis points.
per_step (callable, optional) – hook for cutomizing action of inner loop (messages per step). See docstring of bluesky.plans.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.relative_spiral_square(), bluesky.plans.spiral(), bluesky.plans.relative_spiral(), bluesky.plans.spiral_fermat(), bluesky.plans.relative_spiral_fermat()

sophys.common.plans.annotated_default_plans.rel_spiral(detectors: Sequence[Readable], x_motor: Movable, y_motor: Movable, x_range: float, y_range: float, dr: float, nth: float, *, dr_y: float | None = None, tilt: float = 0.0, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Relative spiral scan

Parameters:

x_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
y_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
x_range (float) – x width of spiral
y_range (float) – y width of spiral
dr (float) – Delta radius along the minor axis of the ellipse.
dr_y (float, optional) – Delta radius along the major axis of the ellipse. If None, it defaults to dr.
nth (float) – Number of theta steps
tilt (float, optional) – Tilt angle in radians, default 0.0
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.spiral(), bluesky.plans.spiral_fermat()

sophys.common.plans.annotated_default_plans.rel_spiral_fermat(detectors: Sequence[Readable], x_motor: Movable, y_motor: Movable, x_range: float, y_range: float, dr: float, factor: float, *, dr_y: float | None = None, tilt: float = 0.0, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Relative fermat spiral scan

Parameters:

detectors (list) – list of ‘readable’ objects
x_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
y_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
x_range (float) – x width of spiral
y_range (float) – y width of spiral
dr (float) – delta radius
factor (float) – radius gets divided by this
dr_y (float, optional) – Delta radius along the major axis of the ellipse, if not specifed defaults to dr
tilt (float, optional) – Tilt angle in radians, default 0.0
per_step (callable, optional) – hook for customizing action of inner loop (messages per step). See docstring of bluesky.plan_stubs.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.spiral(), bluesky.plans.rel_spiral(), bluesky.plans.spiral_fermat()

sophys.common.plans.annotated_default_plans.rel_spiral_square(detectors: Sequence[Readable], x_motor: Movable, y_motor: Movable, x_range: float, y_range: float, x_num: float, y_num: float, *, per_step: Callable[[Sequence[Readable], Mapping[Movable, Any], Mapping[Movable, Any], Callable[[list[Readable]], Generator[Msg, Any, Mapping[str, Reading] | None]] | None], Generator[Msg, Any, None]] = None, md: dict | None = None)[source]

Relative square spiral scan, centered around current (x, y) position.

Parameters:

detectors (list) – list of ‘readable’ objects
x_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
y_motor (object) – any ‘settable’ object (motor, temp controller, etc.)
x_range (float) – x width of spiral
y_range (float) – y width of spiral
x_num (float) – number of x axis points
y_num (float) – Number of y axis points.
per_step (callable, optional) – hook for cutomizing action of inner loop (messages per step). See docstring of bluesky.plans.one_nd_step() (the default) for details.
md (dict, optional) – metadata

See also

bluesky.plans.spiral_square(), bluesky.plans.spiral(), bluesky.plans.relative_spiral(), bluesky.plans.spiral_fermat(), bluesky.plans.relative_spiral_fermat()

sophys.common.plans.annotated_default_plans.adaptive_scan(detectors: Sequence[Readable], target_field: str, motor: Movable, start: float, stop: float, min_step: float, max_step: float, target_delta: float, backstep: bool, threshold: float = 0.8, *, md: dict | None = None)[source]

Scan over one variable with adaptively tuned step size.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
target_field (string) – data field whose output is the focus of the adaptive tuning
motor (object) – any ‘settable’ object (motor, temp controller, etc.)
start (float) – starting position of motor
stop (float) – ending position of motor
min_step (float) – smallest step for fast-changing regions
max_step (float) – largest step for slow-chaning regions
target_delta (float) – desired fractional change in detector signal between steps
backstep (bool) – whether backward steps are allowed – this is concern with some motors
threshold (float, optional) – threshold for going backward and rescanning a region, default is 0.8
md (dict, optional) – metadata

See also

bluesky.plans.rel_adaptive_scan()

sophys.common.plans.annotated_default_plans.rel_adaptive_scan(detectors: Sequence[Readable], target_field: str, motor: Movable, start: float, stop: float, min_step: float, max_step: float, target_delta: float, backstep: bool, threshold: float = 0.8, *, md: dict | None = None)[source]

Relative scan over one variable with adaptively tuned step size.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
target_field (string) – data field whose output is the focus of the adaptive tuning
motor (object) – any ‘settable’ object (motor, temp controller, etc.)
start (float) – starting position of motor
stop (float) – ending position of motor
min_step (float) – smallest step for fast-changing regions
max_step (float) – largest step for slow-chaning regions
target_delta (float) – desired fractional change in detector signal between steps
backstep (bool) – whether backward steps are allowed – this is concern with some motors
threshold (float, optional) – threshold for going backward and rescanning a region, default is 0.8
md (dict, optional) – metadata

See also

bluesky.plans.adaptive_scan()

sophys.common.plans.annotated_default_plans.tune_centroid(detectors: Sequence[Readable], signal: str, motor: Movable, start: float, stop: float, min_step: float, num: int = 10, step_factor: float = 3.0, snake: bool = False, *, md: dict | None = None)[source]

plan: tune a motor to the centroid of signal(motor)

Initially, traverse the range from start to stop with the number of points specified. Repeat with progressively smaller step size until the minimum step size is reached. Rescans will be centered on the signal centroid (for $I(x)$, centroid$= sum{I}/sum{x*I}$) with original scan range reduced by step_factor.

Set snake=True if your positions are reproducible moving from either direction. This will not necessarily decrease the number of traversals required to reach convergence. Snake motion reduces the total time spent on motion to reset the positioner. For some positioners, such as those with hysteresis, snake scanning may not be appropriate. For such positioners, always approach the positions from the same direction.

Note: Ideally the signal has only one peak in the range to be scanned. It is assumed the signal is not polymodal between start and stop.

Parameters:

detectors (list or tuple) – list of ‘readable’ objects
signal (string) – detector field whose output is to maximize
motor (object) – any ‘settable’ object (motor, temp controller, etc.)
start (float) – start of range
stop (float) – end of range, note: start < stop
min_step (float) – smallest step size to use.
num (int, optional) – number of points with each traversal, default = 10
step_factor (float, optional) –
used in calculating new range after each pass

note: step_factor > 1.0, default = 3
snake (bool, optional) – if False (default), always scan from start to stop
md (dict, optional) – metadata

Examples

Find the center of a peak using synthetic hardware.

>>> from ophyd.sim import SynAxis, SynGauss
>>> motor = SynAxis(name='motor')
>>> det = SynGauss(name='det', motor, 'motor',
...                center=-1.3, Imax=1e5, sigma=0.05)
>>> RE(tune_centroid([det], "det", motor, -1.5, -0.5, 0.01, 10))

sophys.common.plans.annotated_default_plans.tweak(detectors: Sequence[Readable], target_field: str, motor: Movable, step: float, *, md: dict | None = None)[source]

Move and motor and read a detector with an interactive prompt.

Parameters:

detetector (Device) –
target_field (string) – data field whose output is the focus of the adaptive tuning
motor (Device) –
step (float) – initial suggestion for step size
md (dict, optional) – metadata

sophys.common.plans.annotated_default_plans.fly(flyers: Sequence[Flyable], *, md: dict | None = None)[source]

Perform a fly scan with one or more ‘flyers’.

Parameters:

flyers (collection) – objects that support the flyer interface
md (dict, optional) – metadata

Yields:

msg (Msg) – ‘kickoff’, ‘wait’, ‘complete, ‘wait’, ‘collect’ messages

See also

bluesky.preprocessors.fly_during_wrapper(), bluesky.preprocessors.fly_during_decorator()