Wrap plans and plan stubs with dictionaries

[EmsArnold]

Closes #1498, and as an alternative to #1702. Scan syntax is more similar to both GDA and bluesky.

Wraps bluesky plans (scan, rel_scan, grid_scan, rel_grid_scan) and plan stubs (rd, stop) for use in blueapi. Intended as a replacement for gda-style start stop step scans until spec_scan is stable and supports start stop step rather than start stop num. Start stop step scans are achieved through generating a list for use with list_scan, rel_list_scan, ...

Concurrent trajectory scans (scan, etc.) and independent trajectory scans (grid_scan, etc.) are both accessed through the same plan and differentiated by number of parameters given for each movable - similar to current GDA-style scans.

Instructions to reviewer on how to test:

1. Do thing x
2. Confirm thing y happens

Checks for reviewer

• Would the PR title make sense to a scientist on a set of release notes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.13%. Comparing base (5955929) to head (615f174).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1734      +/-   ##
==========================================
+ Coverage   99.12%   99.13%   +0.01%     
==========================================
  Files         282      283       +1     
  Lines       10698    10908     +210     
==========================================
+ Hits        10604    10814     +210     
  Misses         94       94              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[RJCD-Diamond]

whatt else does this need until it can not be a draft and be merged?

[EmsArnold]

@RJCD-Diamond, it should be good to go, but could likely use some input on plan names and and other changes.
Perhaps others (@olliesilvester, @noemifrisina, @DominicOram, @oliwenmandiamond, @fajinyuan) would have some opinions on this naming / scanning convention as opposed to the one laid out in #1702.

[RJCD-Diamond]

Why did you go with num_scan when both gda and bluesky refer to this as scan? Are the behaviours different?

[EmsArnold]

Why did you go with num_scan when both gda and bluesky refer to this as scan? Are the behaviours different?

scan in gda is a step scan, hence the distinction of both num_scan and step_scan, to make it more apparent for users coming from either bluesky or gda

[DominicOram]

until spec_scan is stable and supports start stop step rather than start stop num

Does this mean you intend for these to be removed when bluesky/scanspec#186 is done? If so I would put a comment in each plan you intend to retire saying that it will be replaced and pointing to that issue.

Concurrent trajectory scans (scan, etc.) and independent trajectory scans (grid_scan, etc.) are both accessed through the same plan and differentiated by number of parameters given for each movable - similar to current GDA-style scans.

Is this a hard requirement? I think I would rather we have them separate as:

• We can then just point people to https://blueskyproject.io/bluesky/main/plans.html as documentation
• They seem to actually be quite different things and lead to weirdness e.g. snake_axes meaning nothing in some contexts

On that note, having different behaviour based on whether we provide a num for each axis or not is also not intuitive. Again, I would just stick to the bluesky way of being more explicit about what you actually want to do

[DominicOram]

Should: It would be good to assert something here e.g. that the motor is moved the expected number of times or that the detector is read the expected number of times. Otherwise this is just a smoke test. Similarly with other tests in this file.

[EmsArnold]

I've added assertions that the documents contain the correct number of events, resources, etc. to the relevant tests

[DominicOram]

Nit:

Suggested change

	description="Dictionary of 'device: paramater' keys. For concurrent "
	description="Dictionary of 'device: parameter' keys. For concurrent "

[DominicOram]

(Also in the rest of the file)

[EmsArnold]

Done!

[RJCD-Diamond]

@EmsArnold Been using this for commissioning purposes on i22 - and strongly suggest we make sure that all of these plans stubs wait for the plan to finish by default

[EmsArnold]

Does this mean you intend for these to be removed when bluesky/scanspec#186 is done? If so I would put a comment in each plan you intend to retire saying that it will be replaced and pointing to that issue.

I think we should reduce the number of plans which result in the same functional scan (i.e. having two plans which do a scan based on start stop num, one bluesky and one scanspec), as this will likely cause confusion for scientists and users when determining which plan they want to use. As to when (or even if) these plans move from bluesky to scanspec is a question of added utility - i.e. if scanspec can easily add the option to flyscan with limited onus upon the user. If there will be no improvement moving from bluesky to scanspec, then there seems to be no reason to change.

Is this a hard requirement?

No, I only implemented the plans this way (implicit scan type, familiar for GDA users) as a comparison to #1702 (explicit scan type, familiar to bluesky users). If there is a consensus to shift from the implicit GDA style to an explicit bluesky style (and we believe this would benefit scientists and users in the future), I am happy to make the swap.

[fajinyuan]

Sorry for comments so late due to holiday leaves. I support @DominicOram suggestion that all scans should be explicitly named so its behaviour doesn't depend on the number of parameters in the input - I regard this feature in GDA scan is a bad design as users need to read doc or use help to discover what each scan syntax does. in the new system we should make these explicitly and then enforce the number of parameters checking for each command in command pre-processor or parser.

[EmsArnold]

@DominicOram , I have swapped the plans from implicit to explicit for ...scan and ...grid_scan, and added comments to note future intention to migrate to using scanspec for num_scan and step_scan type scans. As far as I can tell, scanspec doesn't have a spec similar to list_scan (short of concatenating a series of Static specs?). As such, there's currently no intention to migrate list_scan type plans to scanspec.