What are the objects to control?#

A user requests a tool to describe all objects (and children) for control. In Bluesky, these objects are either a single Signal or a Device (a nested structure of Device and Signal objects).

There are several tools available to learn what the control system provides. Because the control system may provide access to dozens, hundreds, or even thousands of control objects, there are several tools, depending on the detail sought. For example, a single motor control (of class EpicsMotor) provides access to ~20 signals.

SUGGESTION

  1. Use listobjects() to get the Device and Signal objects for control.

  2. Use listdevice(OBJECT) to learn more about a specific Device or Signal object.

  3. Use listplans() to learn the plans available for control.

  4. Use findCatalogsInNamespace() to learn the available databroker catalogs.

OVERVIEW

This guide describes these tools to learn more about your Bluesky control system:

  • apstools.utils.listobjects(): list of top-level objects available at the command line.

  • apstools.utils.listdevice(): internal objects of a single object.

  • Every Device has a .summary() method that summarizes the device’s internal objects.

  • The command-line (only) magic: %wa prints tables of ophyd-labeled Signal objects.

  • apstools.utils.listplans(): list of top-level bluesky plans available at the command line.

  • apstools.utils.findCatalogsInNamespace(): Returns a dictionary with the databroker catalogs available at the command line.

For SPEC Users

For those with experience using the SPEC software, this comparison table may be of assistance in learning the command-line tools available in Bluesky:

SPEC

Bluesky

comments

wa

%wa motor

Show all the motors and their positions, limits, etc.

-n/a-

listobjects()

List all the controllable devices (the ones known at the command-line level).

lsdef

listplans()

List all the bluesky plans (the ones known at the command-line level).

-n/a-

PLAN?

Show the documentation of the Bluesky plan. Works with other Python objects, too.

prdef MACRO

PLAN??

Show the source code of the SPEC macro or Bluesky plan. Works with other Python objects, too.

qdo FILE.mac

%run -i FILE.py

Run the definitions and commands provided in the file.

u UNIX_CMD

!UNIX_CMD

Run a command in the (UNIX) shell.

Start local control system

Start a Bluesky control system to demonstrate these functions. We’ll start the bluesky training instrument in the same way as the other How-to guides here.

[1]:
import pathlib, sys
sys.path.append(str(pathlib.Path().home() / "bluesky"))
from instrument.collection import *
I Sun-14:22:27 - Console logging: /home/prjemian/Documents/projects/BCDA-APS/apstools/docs/source/examples/.logs/ipython_console.log
I Sun-14:22:27 - ############################################################ startup
I Sun-14:22:27 - logging started
I Sun-14:22:27 - logging level = 10
I Sun-14:22:27 - /home/prjemian/bluesky/instrument/session_logs.py
I Sun-14:22:27 - /home/prjemian/bluesky/instrument/collection.py
I Sun-14:22:27 - CONDA_PREFIX = /home/prjemian/.conda/envs/bluesky_2023_2
I Sun-14:22:27 - xmode exception level: 'Minimal'
I Sun-14:22:27 - /home/prjemian/bluesky/instrument/mpl/notebook.py
/home/prjemian/bluesky/instrument/_iconfig.py
Activating auto-logging. Current session state plus future input saved.
Filename       : /home/prjemian/Documents/projects/BCDA-APS/apstools/docs/source/examples/.logs/ipython_console.log
Mode           : rotate
Output logging : True
Raw input log  : False
Timestamping   : True
State          : active
Exception reporting mode: Minimal
I Sun-14:22:28 - #### Bluesky Framework ####
I Sun-14:22:28 - /home/prjemian/bluesky/instrument/framework/check_python.py
I Sun-14:22:28 - /home/prjemian/bluesky/instrument/framework/check_bluesky.py
I Sun-14:22:29 - /home/prjemian/bluesky/instrument/framework/initialize.py
I Sun-14:22:29 - using databroker catalog 'training'
I Sun-14:22:29 - using ophyd control layer: pyepics
I Sun-14:22:29 - /home/prjemian/bluesky/instrument/framework/metadata.py
I Sun-14:22:29 - /home/prjemian/bluesky/instrument/epics_signal_config.py
I Sun-14:22:29 - Using RunEngine metadata for scan_id
I Sun-14:22:29 - #### Devices ####
I Sun-14:22:29 - /home/prjemian/bluesky/instrument/devices/area_detector.py
I Sun-14:22:29 - /home/prjemian/bluesky/instrument/devices/calculation_records.py
I Sun-14:22:32 - /home/prjemian/bluesky/instrument/devices/fourc_diffractometer.py
I Sun-14:22:32 - /home/prjemian/bluesky/instrument/devices/ioc_stats.py
I Sun-14:22:32 - /home/prjemian/bluesky/instrument/devices/kohzu_monochromator.py
I Sun-14:22:32 - /home/prjemian/bluesky/instrument/devices/motors.py
I Sun-14:22:32 - /home/prjemian/bluesky/instrument/devices/noisy_detector.py
I Sun-14:22:33 - /home/prjemian/bluesky/instrument/devices/scaler.py
I Sun-14:22:33 - /home/prjemian/bluesky/instrument/devices/shutter_simulator.py
I Sun-14:22:33 - /home/prjemian/bluesky/instrument/devices/simulated_fourc.py
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/devices/simulated_kappa.py
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/devices/sixc_diffractometer.py
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/devices/temperature_signal.py
I Sun-14:22:34 - #### Callbacks ####
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/callbacks/spec_data_file_writer.py
I Sun-14:22:34 - #### Plans ####
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/plans/lup_plan.py
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/plans/peak_finder_example.py
I Sun-14:22:34 - /home/prjemian/bluesky/instrument/utils/image_analysis.py
I Sun-14:22:34 - #### Utilities ####
I Sun-14:22:34 - writing to SPEC file: /home/prjemian/Documents/projects/BCDA-APS/apstools/docs/source/examples/20230312-142234.dat
I Sun-14:22:34 -    >>>>   Using default SPEC file name   <<<<
I Sun-14:22:34 -    file will be created when bluesky ends its next scan
I Sun-14:22:34 -    to change SPEC file, use command:   newSpecFile('title')
I Sun-14:22:34 - #### Startup is complete. ####

listobjects() function#

Q: What are the objects available for control?

A: listobjects() lists all the Device and Signal (technically, all ophyd.ophydobj.OphydObject) objects at the command-line level.

Let’s demonstrate:

[2]:
from apstools.utils import listobjects
listobjects()
[2]:
=========== ================================ ============== ===================
name        class                            PV (or prefix) label(s)
=========== ================================ ============== ===================
I0          EpicsSignalRO                    gp:scaler1.S2  channel counter
I00         EpicsSignalRO                    gp:scaler1.S6  channel counter
I000        EpicsSignalRO                    gp:scaler1.S5  channel counter
adsimdet    SimDetector_V34                  ad:            area_detector
calcouts    UserCalcoutDevice                gp:
calcs       UserCalcsDevice                  gp:
dcm         MyKohzu                          gp:
diode       EpicsSignalRO                    gp:scaler1.S4  channel counter
fourc       FourCircle                       gp:
gp_stats    IocInfoDevice                    gp:
m1          MyEpicsMotor                     gp:m1          motor
m10         MyEpicsMotor                     gp:m10         motor
m11         MyEpicsMotor                     gp:m11         motor
m12         MyEpicsMotor                     gp:m12         motor
m13         MyEpicsMotor                     gp:m13         motor
m14         MyEpicsMotor                     gp:m14         motor
m15         MyEpicsMotor                     gp:m15         motor
m16         MyEpicsMotor                     gp:m16         motor
m2          MyEpicsMotor                     gp:m2          motor
m3          MyEpicsMotor                     gp:m3          motor
m4          MyEpicsMotor                     gp:m4          motor
m5          MyEpicsMotor                     gp:m5          motor
m6          MyEpicsMotor                     gp:m6          motor
m7          MyEpicsMotor                     gp:m7          motor
m8          MyEpicsMotor                     gp:m8          motor
m9          MyEpicsMotor                     gp:m9          motor
noisy       EpicsSignalRO                    gp:userCalc1   detectors simulator
scaler1     ScalerCH                         gp:scaler1     scalers detectors
scint       EpicsSignalRO                    gp:scaler1.S3  channel counter
shutter     SimulatedApsPssShutterWithStatus                shutters
sim4c       SimulatedE4CV
simk4c      SimulatedK4CV
simk6c      SimulatedK6C
sixc        SixCircle                        gp:
temperature MyPvPositioner                   gp:userCalc8
timebase    EpicsSignalRO                    gp:scaler1.S1  channel counter
=========== ================================ ============== ===================

The listobjects() function has options, specified as keyword arguments. To learn more, ask IPython for help, using listobjects?:

[3]:
listobjects?
Signature:
listobjects(
    show_pv=True,
    printing=None,
    verbose=False,
    symbols=None,
    child_devices=False,
    child_signals=False,
    table_style=<TableStyle.pyRestTable: <class 'apstools.utils._core.PRT_Table'>>,
)
Docstring:
Show all the ophyd Signal and Device objects defined as globals.

PARAMETERS

show_pv
    *bool* :
    If True, also show relevant EPICS PV, if available.
    (default: True)
printing *bool* :
    Deprecated.
verbose
    *bool* :
    If True, also show ``str(obj``.
    (default: False)
symbols
    *dict* :
    If None, use global symbol table.
    If not None, use provided dictionary.
    (default: ``globals()``)
child_devices
    *bool* :
    If True, also show how many Devices are children of this device.
    (default: False)
child_signals
    *bool* :
    If True, also show how many Signals are children of this device.
    (default: False)
table_style *object* :
    Either ``apstools.utils.TableStyle.pandas`` (default) or
    using values from :class:`apstools.utils.TableStyle`.

    .. note:: ``pandas.DataFrame`` wll truncate long text
       to at most 50 characters.

RETURNS

object:
    Instance of ``pyRestTable.Table()``

EXAMPLE::

    In [1]: listobjects()
    ======== ================================ =============
    name     ophyd structure                  EPICS PV
    ======== ================================ =============
    adsimdet MySingleTriggerSimDetector       vm7SIM1:
    m1       EpicsMotor                       vm7:m1
    m2       EpicsMotor                       vm7:m2
    m3       EpicsMotor                       vm7:m3
    m4       EpicsMotor                       vm7:m4
    m5       EpicsMotor                       vm7:m5
    m6       EpicsMotor                       vm7:m6
    m7       EpicsMotor                       vm7:m7
    m8       EpicsMotor                       vm7:m8
    noisy    EpicsSignalRO                    vm7:userCalc1
    scaler   ScalerCH                         vm7:scaler1
    shutter  SimulatedApsPssShutterWithStatus
    ======== ================================ =============

    Out[1]: <pyRestTable.rest_table.Table at 0x7fa4398c7cf8>

    In [2]:

(new in apstools release 1.1.8)
File:      ~/Documents/projects/BCDA-APS/apstools/apstools/utils/misc.py
Type:      function

listdevice() function#

Once a specific Device or Signal object has been identified, use listdevice(OBJECT) to report about its internal controls.

Let’s demonstrate with a couple devices from the above table. The noisy object is a EpicsSignalRO (a read-only Signal which connects with an EPICS PV). It has no internals structure, just a time-stamped value.

[4]:
from apstools.utils import listdevice
listdevice(noisy)
[4]:
========= ================== ==========================
data name value              timestamp
========= ================== ==========================
noisy     255.82191640413177 2023-03-12 14:22:33.135021
========= ================== ==========================

The temperature object is a MyPvPositioner which uses a calculation record to simulate a temperature controller.

[5]:
listdevice(temperature)
[5]:
=============================== =================================== ==========================
data name                       value                               timestamp
=============================== =================================== ==========================
temperature_setpoint            25.0                                2023-03-12 14:22:34.218341
temperature                     25.0                                2023-03-12 14:22:34.222096
temperature_done                True                                2023-03-12 14:22:34.228893
temperature_calculation         A+max(-D,min(D,(B-A)))+C*(RNDM-0.5) 2023-03-12 14:22:34.224162
temperature_description         temperature                         2023-03-12 14:22:34.215664
temperature_max_change          2.0                                 2023-03-12 14:22:34.223119
temperature_noise               1.0                                 2023-03-12 14:22:34.222096
temperature_previous_value_pv   gp:userCalc8.VAL                    2023-03-12 14:22:34.215664
temperature_scanning_rate       5                                   2023-03-12 14:22:34.224162
temperature_tolerance           1.0                                 2023-03-12 14:22:34.224162
temperature_report_dmov_changes False                               2023-03-12 14:22:34.217478
=============================== =================================== ==========================

The fourc object is a FourCircle diffractometer with various internal controls. One of the controls is the fourc.omega motor, connected to EPICS as EpicsMotor. This is its internal controls object structure.

[6]:
listdevice(fourc.omega)
[6]:
================================ ======== ==========================
data name                        value    timestamp
================================ ======== ==========================
fourc_omega                      0.0      2023-03-11 14:05:08.019094
fourc_omega_user_setpoint        0.0      2023-03-11 14:05:08.019094
fourc_omega_user_offset          0.0      2023-03-11 14:05:08.019094
fourc_omega_user_offset_dir      0        2023-03-11 14:05:08.019094
fourc_omega_offset_freeze_switch 0        2023-03-11 14:05:08.019094
fourc_omega_set_use_switch       0        2023-03-11 14:05:08.019094
fourc_omega_velocity             1.0      2023-03-11 14:05:08.019094
fourc_omega_acceleration         0.2      2023-03-11 14:05:08.019094
fourc_omega_motor_egu            degrees  2023-03-11 14:05:08.019094
fourc_omega_motor_is_moving      0        2023-03-11 14:05:08.019094
fourc_omega_motor_done_move      1        2023-03-11 14:05:08.019094
fourc_omega_high_limit_switch    0        2023-03-11 14:05:08.019094
fourc_omega_low_limit_switch     0        2023-03-11 14:05:08.019094
fourc_omega_high_limit_travel    32000.0  2023-03-11 14:05:08.019094
fourc_omega_low_limit_travel     -32000.0 2023-03-11 14:05:08.019094
fourc_omega_direction_of_travel  0        2023-03-11 14:05:08.019094
fourc_omega_motor_stop           0        2023-03-11 14:05:08.019094
fourc_omega_home_forward         0        2023-03-11 14:05:08.019094
fourc_omega_home_reverse         0        2023-03-11 14:05:08.019094
================================ ======== ==========================

This instrument uses a simulated shutter. Show its internal structure:

[7]:
listdevice(shutter)
[7]:
==================== ===== ==========================
data name            value timestamp
==================== ===== ==========================
shutter_busy         False 2023-03-12 14:22:33.990247
shutter_open_signal  0     2023-03-12 14:22:33.990307
shutter_close_signal 0     2023-03-12 14:22:33.990352
shutter_pss_state    close 2023-03-12 14:22:33.990411
==================== ===== ==========================

One of the calculation records uses the readback value of a motor:

[8]:
listdevice(calcs.calc1.channels.A)
[8]:
==================================== ========= ==========================
data name                            value     timestamp
==================================== ========= ==========================
calcs_calc1_channels_A_input_value   0.0       2023-03-12 14:22:32.982288
calcs_calc1_channels_A_input_pv      gp:m1.RBV 2023-03-12 14:22:33.046510
calcs_calc1_channels_A_input_trigger 1         2023-03-12 14:22:33.018162
==================================== ========= ==========================

The listdevice() function has options, specified as keyword arguments. To learn more, ask IPython for help, using listdevice?:

[9]:
listdevice?
Signature:
listdevice(
    obj,
    scope=None,
    cname=False,
    dname=True,
    show_pv=False,
    use_datetime=True,
    show_ancient=True,
    table_style=<TableStyle.pyRestTable: <class 'apstools.utils._core.PRT_Table'>>,
)
Docstring:
Describe the signal information from device ``obj`` in a pandas DataFrame.

Look through all subcomponents to find all the signals to be shown.

PARAMETERS

obj
    *object* : Instance of ophyd Signal or Device.
scope
    *str* or None : Scope of content to be shown.

    - ``"full"`` (or ``None``) shows all Signal components
    - ``"epics"`` shows only EPICS-based Signals
    - ``"read"`` shows only the signals returned by ``obj.read()``

    default: ``None``
cname
    *bool* : Show the _control_ (Python, dotted) name in column ``name``.

    default: ``False``
dname
    *bool* : Show the _data_ (databroker, with underlines) name in
    column ``data name``.

    default: ``True``
show_pv
    *bool* : Show the EPICS process variable (PV) name in
    column ``PV``.

    default: ``False``
use_datetime *bool* :
    Show the EPICS timestamp (time of last update) in
    column ``timestamp``.

    default: ``True``
show_ancient *bool* :
    Show uninitialized EPICS process variables.

    In EPICS, an uninitialized PV has a timestamp of 1990-01-01 UTC.
    This option enables or suppresses ancient values identified
    by timestamp from 1989.  These are values only defined in
    the original ``.db`` file.

    default: ``True``
table_style *object* :
    Either ``apstools.utils.TableStyle.pandas`` (default) or
    using values from :class:`apstools.utils.TableStyle`.

    .. note:: ``pandas.DataFrame`` wll truncate long text
       to at most 50 characters.
File:      ~/Documents/projects/BCDA-APS/apstools/apstools/utils/device_info.py
Type:      function

.summary() method#

Every object using ophyd.Device (or a subclass) has a `.summary() <bluesky/ophyd>`__ method to describe its internal structure. (Note: a Signal does not have a .summary() method.)

The report is divided into sections:

section

description

data keys (* hints)

Names (undotted) of children (as they appear in the databroker) of data.

config keys

Data keys (undotted) in the dictionary returned by the .read_configuration() method.

configuration attrs

List of child (dotted) object names to be reported by the .read_configuration() method.

read attrs

List of child (dotted) object names to be reported by the .read() method.

unused attrs

Data keys (undotted) not used by either .read() or .read_configuration().

For example, this is a summary of one of the calculation (EPICS swait record) channels:

[10]:
calcs.calc1.channels.A.summary()
data keys (* hints)
-------------------

read attrs
----------
input_value          EpicsSignal         ('calcs_calc1_channels_A_input_value')

config keys
-----------
calcs_calc1_channels_A_input_pv
calcs_calc1_channels_A_input_trigger
calcs_calc1_channels_A_input_value

configuration attrs
-------------------
input_value          EpicsSignal         ('calcs_calc1_channels_A_input_value')
input_pv             EpicsSignal         ('calcs_calc1_channels_A_input_pv')
input_trigger        EpicsSignal         ('calcs_calc1_channels_A_input_trigger')

unused attrs
------------

The content of the .summary() method increases with the complexity of the device. Such as the fourc.omega motor:

[11]:
fourc.omega.summary()
data keys (* hints)
-------------------
*fourc_omega
 fourc_omega_user_setpoint

read attrs
----------
user_readback        EpicsSignalRO       ('fourc_omega')
user_setpoint        EpicsSignal         ('fourc_omega_user_setpoint')

config keys
-----------
fourc_omega_motor_egu

configuration attrs
-------------------
motor_egu            EpicsSignal         ('fourc_omega_motor_egu')

unused attrs
------------
user_offset          EpicsSignal         ('fourc_omega_user_offset')
user_offset_dir      EpicsSignal         ('fourc_omega_user_offset_dir')
offset_freeze_switch EpicsSignal         ('fourc_omega_offset_freeze_switch')
set_use_switch       EpicsSignal         ('fourc_omega_set_use_switch')
velocity             EpicsSignal         ('fourc_omega_velocity')
acceleration         EpicsSignal         ('fourc_omega_acceleration')
motor_is_moving      EpicsSignalRO       ('fourc_omega_motor_is_moving')
motor_done_move      EpicsSignalRO       ('fourc_omega_motor_done_move')
high_limit_switch    EpicsSignalRO       ('fourc_omega_high_limit_switch')
low_limit_switch     EpicsSignalRO       ('fourc_omega_low_limit_switch')
high_limit_travel    EpicsSignal         ('fourc_omega_high_limit_travel')
low_limit_travel     EpicsSignal         ('fourc_omega_low_limit_travel')
direction_of_travel  EpicsSignal         ('fourc_omega_direction_of_travel')
motor_stop           EpicsSignal         ('fourc_omega_motor_stop')
home_forward         EpicsSignal         ('fourc_omega_home_forward')
home_reverse         EpicsSignal         ('fourc_omega_home_reverse')

%wa magic command#

%wa is a magic command which means it is only available in console or notebook sessions.

First, we show how to list the objects labeled "motor" (singular by bluesky convention), since that is exactly what the SPEC wa command lists:

[12]:
%wa motor
motor
  Positioner                     Value       Low Limit   High Limit  Offset
  dcm_m_theta                    11.18       -32000.0    32000.0     0.0
  dcm_m_y                        -17.84      -32000.0    32000.0     0.0
  dcm_m_z                        90.29       -32000.0    32000.0     0.0
  fourc_chi                      0.0         -32000.0    32000.0     0.0
  fourc_omega                    0.0         -32000.0    32000.0     0.0
  fourc_phi                      0.0         -32000.0    32000.0     0.0
  fourc_tth                      0.0         -32000.0    32000.0     0.0
  m1                             0.0         -32000.0    32000.0     0.0
  m10                            0.0         -32000.0    32000.0     0.0
  m11                            0.0         -32000.0    32000.0     0.0
  m12                            0.0         -32000.0    32000.0     0.0
  m13                            0.0         -32000.0    32000.0     0.0
  m14                            0.0         -32000.0    32000.0     0.0
  m15                            0.0         -32000.0    32000.0     0.0
  m16                            0.0         -32000.0    32000.0     0.0
  m2                             0.0         -32000.0    32000.0     0.0
  m3                             0.0         -32000.0    32000.0     0.0
  m4                             0.0         -32000.0    32000.0     0.0
  m5                             0.65        -32000.0    32000.0     0.0
  m6                             0.35        -32000.0    32000.0     0.0
  m7                             0.0         -32000.0    32000.0     0.0
  m8                             0.0         -32000.0    32000.0     0.0
  m9                             0.0         -32000.0    32000.0     0.0
  sixc_chi                       0.0         -32000.0    32000.0     0.0
  sixc_delta                     0.0         -32000.0    32000.0     0.0
  sixc_gamma                     0.0         -32000.0    32000.0     0.0
  sixc_mu                        0.0         -32000.0    32000.0     0.0
  sixc_omega                     0.0         -32000.0    32000.0     0.0
  sixc_phi                       0.0         -32000.0    32000.0     0.0

  Local variable name                    Ophyd name (to be recorded as metadata)
  dcm.m_theta                            dcm_m_theta
  dcm.m_y                                dcm_m_y
  dcm.m_z                                dcm_m_z
  fourc.chi                              fourc_chi
  fourc.omega                            fourc_omega
  fourc.phi                              fourc_phi
  fourc.tth                              fourc_tth
  m1                                     m1
  m10                                    m10
  m11                                    m11
  m12                                    m12
  m13                                    m13
  m14                                    m14
  m15                                    m15
  m16                                    m16
  m2                                     m2
  m3                                     m3
  m4                                     m4
  m5                                     m5
  m6                                     m6
  m7                                     m7
  m8                                     m8
  m9                                     m9
  sixc.chi                               sixc_chi
  sixc.delta                             sixc_delta
  sixc.gamma                             sixc_gamma
  sixc.mu                                sixc_mu
  sixc.omega                             sixc_omega
  sixc.phi                               sixc_phi

But the %wa magic command can list objects with any label applied. If you leave out the specific label, you’ll get a listing categorized by each of the labels in use.

Note that an object may have zero, one, or several labels; an object will be described under each of its labels.

[13]:
%wa
area_detector
  Local variable name                    Ophyd name (to be recorded as metadata)
  adsimdet                               adsimdet

motor
  Positioner                     Value       Low Limit   High Limit  Offset
  dcm_m_theta                    11.18       -32000.0    32000.0     0.0
  dcm_m_y                        -17.84      -32000.0    32000.0     0.0
  dcm_m_z                        90.29       -32000.0    32000.0     0.0
  fourc_chi                      0.0         -32000.0    32000.0     0.0
  fourc_omega                    0.0         -32000.0    32000.0     0.0
  fourc_phi                      0.0         -32000.0    32000.0     0.0
  fourc_tth                      0.0         -32000.0    32000.0     0.0
  m1                             0.0         -32000.0    32000.0     0.0
  m10                            0.0         -32000.0    32000.0     0.0
  m11                            0.0         -32000.0    32000.0     0.0
  m12                            0.0         -32000.0    32000.0     0.0
  m13                            0.0         -32000.0    32000.0     0.0
  m14                            0.0         -32000.0    32000.0     0.0
  m15                            0.0         -32000.0    32000.0     0.0
  m16                            0.0         -32000.0    32000.0     0.0
  m2                             0.0         -32000.0    32000.0     0.0
  m3                             0.0         -32000.0    32000.0     0.0
  m4                             0.0         -32000.0    32000.0     0.0
  m5                             0.65        -32000.0    32000.0     0.0
  m6                             0.35        -32000.0    32000.0     0.0
  m7                             0.0         -32000.0    32000.0     0.0
  m8                             0.0         -32000.0    32000.0     0.0
  m9                             0.0         -32000.0    32000.0     0.0
  sixc_chi                       0.0         -32000.0    32000.0     0.0
  sixc_delta                     0.0         -32000.0    32000.0     0.0
  sixc_gamma                     0.0         -32000.0    32000.0     0.0
  sixc_mu                        0.0         -32000.0    32000.0     0.0
  sixc_omega                     0.0         -32000.0    32000.0     0.0
  sixc_phi                       0.0         -32000.0    32000.0     0.0

  Local variable name                    Ophyd name (to be recorded as metadata)
  dcm.m_theta                            dcm_m_theta
  dcm.m_y                                dcm_m_y
  dcm.m_z                                dcm_m_z
  fourc.chi                              fourc_chi
  fourc.omega                            fourc_omega
  fourc.phi                              fourc_phi
  fourc.tth                              fourc_tth
  m1                                     m1
  m10                                    m10
  m11                                    m11
  m12                                    m12
  m13                                    m13
  m14                                    m14
  m15                                    m15
  m16                                    m16
  m2                                     m2
  m3                                     m3
  m4                                     m4
  m5                                     m5
  m6                                     m6
  m7                                     m7
  m8                                     m8
  m9                                     m9
  sixc.chi                               sixc_chi
  sixc.delta                             sixc_delta
  sixc.gamma                             sixc_gamma
  sixc.mu                                sixc_mu
  sixc.omega                             sixc_omega
  sixc.phi                               sixc_phi

detectors
  Local variable name                    Ophyd name (to be recorded as metadata)
  noisy                                  noisy
  scaler1                                scaler1

simulator
  Local variable name                    Ophyd name (to be recorded as metadata)
  noisy                                  noisy

scalers
  Local variable name                    Ophyd name (to be recorded as metadata)
  scaler1                                scaler1

channel
  Local variable name                    Ophyd name (to be recorded as metadata)
  I0                                     I0
  I00                                    I00
  I000                                   I000
  diode                                  diode
  scaler1.channels.chan01.s              clock
  scaler1.channels.chan02.s              I0
  scaler1.channels.chan03.s              scint
  scaler1.channels.chan04.s              diode
  scaler1.channels.chan05.s              I000
  scaler1.channels.chan06.s              I00
  scint                                  scint
  timebase                               clock

counter
  Local variable name                    Ophyd name (to be recorded as metadata)
  I0                                     I0
  I00                                    I00
  I000                                   I000
  diode                                  diode
  scaler1.channels.chan01.s              clock
  scaler1.channels.chan02.s              I0
  scaler1.channels.chan03.s              scint
  scaler1.channels.chan04.s              diode
  scaler1.channels.chan05.s              I000
  scaler1.channels.chan06.s              I00
  scint                                  scint
  timebase                               clock

shutters
  Local variable name                    Ophyd name (to be recorded as metadata)
  shutter                                shutter

listplans() function#

Another type of control is the bluesky plan, a Python generator function used by the bluesky RunEngine to perform data acquisition procedures.

Here, we list the plans available when the bluesky training instrument is started:

[14]:
from apstools.utils import listplans
listplans()
[14]:
======================= ==================================================
plan                    doc
======================= ==================================================
lup                     Lineup a positioner.
two_pass_scan           Find the peak of noisy v. m1 in the range of + ...
findpeak_multipass      find peak of noisy v. m1 by repeated scans wit ...
repeat_findpeak         Repeat findpeak_multipass() with new parameter ...
redefine_motor_position Set EPICS motor record's user coordinate to `` ...
======================= ==================================================

Any of these plans may be queried for its help or source code using the ipython ? (help) or ?? (source code) suffixes. Let’s look at one of them in more detail:

[15]:
redefine_motor_position?
Signature: redefine_motor_position(motor, new_position)
Docstring: Set EPICS motor record's user coordinate to ``new_position``.
File:      ~/Documents/projects/BCDA-APS/apstools/apstools/utils/misc.py
Type:      function
[16]:
redefine_motor_position??
Signature: redefine_motor_position(motor, new_position)
Source:
def redefine_motor_position(motor, new_position):
    """Set EPICS motor record's user coordinate to ``new_position``."""
    yield from bps.mv(motor.set_use_switch, 1)
    yield from bps.mv(motor.user_setpoint, new_position)
    yield from bps.mv(motor.set_use_switch, 0)
File:      ~/Documents/projects/BCDA-APS/apstools/apstools/utils/misc.py
Type:      function

The same listplans() command can report the plans from an imported module. Here, using import bluesky.plans as bp):

[17]:
listplans(bp)
[17]:
========================================= ==================================================
plan                                      doc
========================================= ==================================================
bluesky.plans.adaptive_scan               Scan over one variable with adaptively tuned s ...
bluesky.plans.count                       Take one or more readings from detectors.
bluesky.plans.fly                         Perform a fly scan with one or more 'flyers'.
bluesky.plans.grid_scan                   Scan over a mesh; each motor is on an independ ...
bluesky.plans.inner_product_scan          ---
bluesky.plans.list_grid_scan              Scan over a mesh; each motor is on an independ ...
bluesky.plans.list_scan                   Scan over one or more variables in steps simul ...
bluesky.plans.log_scan                    Scan over one variable in log-spaced steps.
bluesky.plans.outer_product_scan          Scan over a mesh; each motor is on an independ ...
bluesky.plans.ramp_plan                   Take data while ramping one or more positioners.
bluesky.plans.rel_adaptive_scan           Relative scan over one variable with adaptivel ...
bluesky.plans.rel_grid_scan               Scan over a mesh relative to current position.
bluesky.plans.rel_list_grid_scan          Scan over a mesh; each motor is on an independ ...
bluesky.plans.rel_list_scan               Scan over one variable in steps relative to cu ...
bluesky.plans.rel_log_scan                Scan over one variable in log-spaced steps rel ...
bluesky.plans.rel_scan                    Scan over one multi-motor trajectory relative  ...
bluesky.plans.rel_spiral                  Relative spiral scan
bluesky.plans.rel_spiral_fermat           Relative fermat spiral scan
bluesky.plans.rel_spiral_square           Relative square spiral scan, centered around c ...
bluesky.plans.relative_adaptive_scan      Relative scan over one variable with adaptivel ...
bluesky.plans.relative_inner_product_scan ---
bluesky.plans.relative_list_scan          Scan over one variable in steps relative to cu ...
bluesky.plans.relative_log_scan           Scan over one variable in log-spaced steps rel ...
bluesky.plans.relative_outer_product_scan Scan over a mesh relative to current position.
bluesky.plans.relative_scan               Scan over one multi-motor trajectory relative  ...
bluesky.plans.relative_spiral             Relative spiral scan
bluesky.plans.relative_spiral_fermat      Relative fermat spiral scan
bluesky.plans.scan                        Scan over one multi-motor trajectory.
bluesky.plans.scan_nd                     Scan over an arbitrary N-dimensional trajectory.
bluesky.plans.spiral                      Spiral scan, centered around (x_start, y_start)
bluesky.plans.spiral_fermat               Absolute fermat spiral scan, centered around ( ...
bluesky.plans.spiral_square               Absolute square spiral scan, centered around ( ...
bluesky.plans.tune_centroid               plan: tune a motor to the centroid of signal(m ...
bluesky.plans.tweak                       Move and motor and read a detector with an int ...
bluesky.plans.x2x_scan                    Relatively scan over two motors in a 2:1 ratio
========================================= ==================================================

Similarly, for the plans provided by apstools:

[18]:
import apstools.plans
listplans(apstools.plans)
[18]:
==================================== ==================================================
plan                                 doc
==================================== ==================================================
apstools.plans.addDeviceDataAsStream Renamed to write_stream().  Will remove with r ...
apstools.plans.documentation_run     Save text as a bluesky run.
apstools.plans.execute_command_list  plan: execute the command list
apstools.plans.label_stream_stub     Writes ophyd-labeled objects to open bluesky r ...
apstools.plans.label_stream_wrapper  Decorator support: Write labeled device(s) to  ...
apstools.plans.lineup                Lineup and center a given axis, relative to cu ...
apstools.plans.nscan                 Scan over ``n`` variables moved together, each ...
apstools.plans.request_input         Request input from the user.  Returns ``True`` ...
apstools.plans.run_blocking_function Run a blocking function as a bluesky plan, in  ...
apstools.plans.run_command_file      plan: execute a list of commands from a text o ...
apstools.plans.sscan_1D              simple 1-D scan using EPICS synApps sscan record
apstools.plans.stage_sigs_wrapper    Save stage_sigs from each device and restore a ...
apstools.plans.tune_axes             Bluesky plan to tune a list of axes in sequence.
apstools.plans.write_stream          add an ophyd Device as an additional document  ...
==================================== ==================================================

findCatalogsInNamespace() function#

To learn what databroker catalogs are already loaded (in the default namespace), use apstools.utils.findCatalogsInNamespace():

[19]:
from apstools.utils import findCatalogsInNamespace
findCatalogsInNamespace()
[19]:
{'cat': <Intake catalog: training>}

It is also possible to get a list of available databroker catalog names using the databroker package. This list includes any catalogs with available configuration details, even if they are not loaded into memory yet.

[20]:
import databroker
list(databroker.catalog)
[20]:
['bdp2022',
 'class_2021_03',
 '6idb_export',
 'apstools_test',
 'class_data_examples',
 'usaxs_test',
 'korts202106',
 'training']
[ ]: