DOC howto setup APS data management in a plan

[prjemian]

Need to describe how to setup APS Data Management in a custom bluesky plan.

[prjemian]

Pull examples from today's discussion with APS POLAR beamline.

[prjemian]

• DM
  • "experiment"
  • "workflow"
  • "DAQ"
  • environment variables
    • DM_SETUP_FILE
    • dm_setup.py
    • Import on startup: https://github.com/aps-8id-dys/bluesky/blob/d2481c7a865ecd2e6306378e405c2814c26a79d8/instrument/framework/__init__.py#L33
• Which style?
  • acquire, then run DM workflow and wait (or not): XPCS example
  • DM workflow interacts with data acquisition (TODO: find that example)
• The setup_user plan
  • connects Python with DM experiment
  • identify DM data directory (such as @voyager)
  • starts (or connects with existing) DM DAQ
  • Examples
    • XPCS
    • others (TODO)
• The data acquisition plan(s):
  • plan API
    • no positional arguments
    • only keywords with valid defaults
    • keywords for measurement, area detectors, metadata, DM, ...
  • validate as needed
  • various setup as needed
    • area detector
    • acquisition
    • DM
    • auxiliary files (such as area detector mask)
    • NeXus master file writer
  • update bluesky metadata dict
    • additional plan metadata
    • DM metadata
    • user-provided metadata
  • create DM workflow object (ophyd device to get its data into the run)
    • configure reporting
  • define the inner acquire() plan
    • bluesky data acquisition here (includes callbacks, stage, open_run)
  • uids = yield from acquire()
  • start the DM workflow: yield from dm_workflow.run_as_plan(
  • wait for workflow to finish (optional)
  • share_bluesky_metadata_with_dm(experiment_name, workflow_name, run)

[prjemian]

Often forgotten is how to setup the environment variables.

[prjemian]

Can this be described more simply? Generalize?

[prjemian]

Lots of the DM code custom to the XPCS demo has been hoisted to apstools, some with differences in implementation.