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
Use
listobjects()to get theDeviceandSignalobjects for control.Use
listdevice(OBJECT)to learn more about a specificDeviceorSignalobject.Use
listplans()to learn the plans available for control.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
Devicehas a.summary()method that summarizes the device’s internal objects.The command-line (only) magic:
%waprints tables of ophyd-labeledSignalobjects.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 |
|---|---|---|
|
|
Show all the motors and their positions, limits, etc. |
-n/a- |
|
List all the controllable devices (the ones known at the command-line level). |
|
|
List all the bluesky plans (the ones known at the command-line level). |
-n/a- |
|
Show the documentation of the Bluesky plan. Works with other Python objects, too. |
|
|
Show the source code of the SPEC macro or Bluesky plan. Works with other Python objects, too. |
|
|
Run the definitions and commands provided in the file. |
|
|
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 |
configuration attrs |
List of child (dotted) object names to be reported by the |
read attrs |
List of child (dotted) object names to be reported by the |
unused attrs |
Data keys (undotted) not used by either |
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']
[ ]: