Simplify Device API

[ZLLentz]

Expected Behavior

API should be simple, extensible, and easy to maintain/apply to new devices.

Current Behavior

It is difficult to extend and maintain the API, both here and on existing devices, because it is built around creating a new method or property for each new feature. To my knowledge, the current API involves the following: .insert(), .remove(), .inserted, .removed, .transmission, .subscribe(SUB_STATE), .branches, .destination, .md.z, .md.beamline

To my knowledge, these are also not documented fully. It is easy to accidentally remove or change the behavior of one of these methods and break lightpath.

Possible Solution

Instead of overloading many methods with special meanings that lightpath expects, limit the number of interface points and name them clearly so that it is clear what they are for.

Quick "didn't think for super long or consult anyone" proposal:

• .lightpath_update(beam_params): method that takes in a beam parameters dict and returns an updated parameter set based on the device's state. Note how this allows us to seamlessly extend/customize which parameters we track along the beamline. For branching devices, this method could take and return tuples of parameters for multiple inputs/outputs.
• .lightpath_clear(): method that brings the device into a state where it is expected to no longer modify the beam parameters

Context

Some devices in pcdsdevices no longer work in lightpath because we adjusted them slightly.

[klauer]

I like the proposed solution. Some random thoughts/ideas:

• Enforce using dictionaries, even for multiple inputs/outputs (name the individual inputs/outputs)
• I'd say a fallback could be a namedtuple, but don't think that would really apply here
• SUB_LIGHTPATH :)

I may be missing something here - feel free to clue me in if so:

• lightpath_update should never mutate the device, and only process inputs to determine the downstream beamparam dict (for testing purposes and such)
• If the intent is that it mutate the device, perhaps it could be split into lightpath_evaluate_what_my_output_state_would_be vs lightpath_update_current_state or something?
• lightpath_clear is akin to remove - but what would be analogous to insert?

[ZLLentz]

• I like your added thoughts.
• I agree that lightpath_update should never change the state of the beamline in anyway, just report it. But here you open an interesting idea of baking in a "what would the light state be if I did x?"
• It's not obvious to me that the lightpath should be in the business of inserting devices (or for that matter, removing them). But we could think of a good name if we need this.

[tangkong]

We reworked the lightpath interface in #133, incorporating much of the spirit of this issue.

It took a while but we did it!