show how to connect energy from local controls

[prjemian]

fixes #25, fixes #26, fixes #42

[prjemian]

@ambarb, @gfabbris: If you have time, can you look over the documentation added here (in the changes) and see if it answers the requests in #25 & #26. Seems a bit wordy to me.

[ambarb]

@prjemian I can this afternoon. Hope that is ok

[mrakitin]

Looks good. I left a few sphinx-related and style comments.

[mrakitin]

Thanks, Pete!

[gfabbris]

otherwise looks good to me.

[ambarb]

If optics:energy_locked is 0 (do not update calc engine), and someone wants to update the calc engine's energy manually, is there a way to do this with the energy_offset applied? I don't think this is part of the commit so I will continue to look, but maybe this is something we missed the first time around.

Otherwise the wording of things is clear. I particularly appreciate you explaining the sign convention you employed for energy_offset. I looked for the math first, so maybe move that explanation before the code block???

It might be, especially for the simulation example, nice to have URL link(s) on how to setup orientation matrix for convenience.

[prjemian]

@ambarb: It is possible to update the calc engine's energy manually. Need to do the various steps in the _energy_changed() method:

If you know the numbers:

diffractometer.calc.energy = (energy_eV + offset_eV) * 0.001

If you use the signals (and know the signals are in eV:

diffractometer.calc.energy = (diffractometer.energy.get()+ diffractometer.energy_offset.get()) * 0.001

...

I'll add this and your other suggestions.

[prjemian]

slightly easier way is:

1. %mov diffractometer.energy_update_calc 1
2. diffractometer._energy_changed(diffractometer.energy.get())
3. %mov diffractometer.energy_update_calc 0

[prjemian]

BUT, setting diffractometer.calc.energy should appear before diffractometer.energy since the former is the standard, the latter is a convenience. That can be stated in the first example.

[ambarb]

@prjemian regarding #41 (comment)

This is basically what we do now, but nicer in that we reduce chance of a mistake. I ask if we can make the method for both locked and unlocked the same so as to have more of a consistent user experience. Maybe this is an enhancement?

[prjemian]

Can do.