Get a result out of a plan

[danielballan]

876 prompted discussion about establishing a pattern for letting plans return some result for interactive use. This has come up only incidentally on the NSLS-II floor so far. We have employed various works arounds such as:

• just printing the result (obvious losing programmatic access to it -- bad!)
• stashing it in RE.md (mixes abstractions badly, and requires the plan to hold a ref to the RunEngine instance)

This might be the way to go:

import bluesky.plans as bp
import inspect

class Foo:
    """
    Perform a scan and collect the readings (in leui of some interesting analysis.)
    """
    def __init__(self):a
        self.result = None

    def __call__(self, *args, **kwargs):
        result = []
        ret_val = None
        for msg in bp.scan(*args, **kwargs):
            if msg.command == 'read':
                reading = yield msg
                result.append(reading)
            else:
                ret_val = yield msg
        self.result = result
        return ret_val
    __call__.__signature__ = inspect.signature(bp.scan)

from bluesky import RunEngine
from ophyd.sim import motor, det  # apologies -- this uses work currently in progress in ophyd
RE = RunEngine({})

foo = Foo()

RE(foo([det], motor, 1, 5 ,5))
foo.result  # has a bunch of collected data -- but this could an analysis result

[prjemian]

Perhaps even a method of a class? Such as a stage that has default settings when tuning?

class SomeStage(Device):
    # ...
    # motor, detector, min_step are set by other methods
    def tune(start, stop):
        yield from tune_centroid([self.detector], self.detector.name, self.motor, start, stop, self.min_step)
        self.centroid = motor.read()[motor.name]["value"] # replace with Tom's suggested revision

[danielballan]

Device methods that return plans are an interesting direction to explore. Currently there are zero examples of this.

[tacaswell]

I am :+1: on devices knowing how to create plans using them selves.

Some quibbles about how much state the device should store vs how much should be passed in and what the scope of what the SomeStage device owns should be.

[tacaswell]

I have been thinking about this and have started to think we should stash the uids on an RE property and let the plan return what ever it wants.

It is a pretty big API change, but I have not seen the return from RE() being used except in a few cases where it would be better handled by a callback on the RE or by capturing the uids returned by the start message.

[danielballan]

Interesting. For what it's worth, I do make use of

uid = RE(...)
db[uid]

widely in tutorials and examples, but I agree that anecdotally that uptake by users does not seem to be high. Using db[-1] some future db[RE.uids] would be fine too.

It does seem like

result = RE(...)

and

def overnight():
    result1 = yield from plan1(...)
    print(result1)
    result2 = yield from plan2(...)
    print(result2)

RE(overnight())

would be popular and nice to have.

[mrakitin]

What about the following scenario?

def overnight():
    result1 = yield from plan1(...)
    result2 = yield from plan2(...)
    return result1, result2

result1, result2 = RE(overnight())
# do some stuff with result1 and result2 interactively

[danielballan]

Yep, I agree that is a better version of overnight.

I think the take-away message is: by allowing plans to return anything they want, as opposed to standardizing on uid(s), as we currently do, plans can straightforwardly return results (1) for use by other sub-plans (2) through RE.__call__ back to the user.

[tacaswell]

Do we have any rules on what plans return right now? I think we can do @danielballan 's version of overnight right now. The RE just ignores the return value and returns the uids from __call__ instead.

[danielballan]

I would be interested in feedback on this latest proposal from @prjemian @teddyrendahl @ZLLentz. To summarize:

Current situation

• RE(plan(...)) always returns the uid(s) of the RunStart documents emitted while executing plan. If plan happens to be a coroutine, it has a final return value, but that value is swallowed/ignored by the RunEngine. RE() always return the RunStart uids, regardless of what the plan returns.
• By convention, plans that generate runs return the uid of that run, which can be used internally in multi-run plans, such as:

  def plan():
      yield from close_shutter()
      dark_uid = yield from count(...)
      yield from open_shutter()
      light_uid = yield from count(..., md={'dark_frame_run_uid': dark_uid})

Proposal

• RE(plan(...)) will return whatever the plan returns, if the plan is a coroutine. If the plan is a list or some other iterable, RE() will return None.
• Plans will be allowed to return other objects, such as fit models, as appropriate to their purpose.

Advantages

• This gives users a natural way to get results out of plans: result = RE(plan(...))
• For use cases where returning uids is still useful, it is still supported. (The dark frame example above will still work as is.) We are just making other usages possible by letting the plan decide what ultimately gets returned to the user through RE().
• This is not a drastic change. Plan stubs already return a variety of objects: abs_set return a Status object; open_run returns a uid string; etc. The convention we propose relaxing here only ever applied to plans that created a run, and it was not enforced by any technical means.

[ZLLentz]

I'm 100% on-board with having the RE return the plan result.

To compensate, perhaps LiveTable should be made to print the uids along with the tables? I imagine there are use cases for grabbing these uids interactively.

[tacaswell]

A edge we will have to deal with is that currently __call__ returns the uids collected so far, so if you pause it, it will return something (maybe an empty list). If we start returning the return value of the plan then we can not do this. I think this is ok and will mostly break people who are using RE inside of for-loops so I don't feel too bad.

[danielballan]

And you get back the same information again anyway when you call RE.stop() (or similar).

[tacaswell]

Actually, re-considering my comment from May, when you interrupt the RE we now raise so we can avoid having to return anything. The issue @danielballan points out is still a problem, when you call stop() the plan may not gracefully exit, hence has no return value we can recover (but we should check to see if it did catch the exception and return instead. Probably just return None otherwise?