Frequently Asked Questions#

How do I enable or disable live plots during scans?#

Live plots are controlled by the BEC.PLOTS setting in iconfig.yml:

BEC:
  PLOTS: false   # set to true to enable live plots

This setting applies at startup. For non-GUI sessions (e.g. SSH without X forwarding) keep it false.

You can also toggle plots within a running session without restarting:

bec.enable_plots()    # turn on live plots for subsequent scans
bec.disable_plots()   # turn off live plots

Similarly, you can control the printed table and baseline report:

bec.enable_table()      # show scan data as a table in the terminal
bec.disable_table()
bec.enable_baseline()   # print baseline readings at the start of each scan
bec.disable_baseline()

How do I add or remove a device from the baseline?#

The baseline stream records all tagged devices once before and once after every scan, providing a passive log of instrument state.

Persistent change (recommended)#

Add or remove the "baseline" label from the device entry in devices.yml, then reload devices:

# devices.yml — add "baseline" to make a device part of the baseline
id4_common.devices.my_device.MyDevice:
  - name: mydev
    labels: ["core", "4idb", "baseline"]   # <-- add "baseline" here

reload_all_devices()   # re-reads devices.yml and reconnects everything

Runtime change (current session only)#

Load a device and it will be added to the baseline automatically if its devices.yml entry carries the "baseline" label:

load_device("mydev")      # connects device; adds to baseline if labelled

Remove a device from both the registry and the baseline:

remove_device("mydev")    # disconnects and removes from baseline

To inspect which devices are currently in the baseline:

[d.name for d in sd.baseline]

How do I pause, resume, or abort a running scan?#

Press Ctrl-C once during a scan to request a deferred pause — the RunEngine finishes the current step before stopping. Then:

RE.resume()   # continue from where the scan paused
RE.stop()     # end the scan cleanly; data collected so far is saved
RE.abort()    # end the scan; run is marked exit_status='aborted'
RE.halt()     # emergency stop — no cleanup, use as a last resort

Key differences:

Command	Cleanup runs?	Exit status
`RE.resume()`	— (continues)	—
`RE.stop()`	Yes	`success`
`RE.abort()`	Yes	`aborted`
`RE.halt()`	No	`fail`

Data from stopped or aborted scans is still saved to the catalog and SPEC file. RE.halt() may leave hardware in an undefined state — prefer RE.stop() or RE.abort() unless there is an emergency.

Why did my scan pause automatically?#

The RunEngine installs shutter suspenders at startup. If the photon shutter closes mid-scan (e.g. due to a beam dump, interlock trip, or manual close), the RunEngine automatically suspends rather than continuing with no beam. It will resume automatically once the shutter re-opens.

If you need to check the current RunEngine state:

RE.state      # 'running', 'paused', 'idle', etc.

If the beam has returned but the scan has not resumed after a minute, you can resume manually:

RE.resume()

If you want to abort instead of waiting:

RE.abort()

How do I find the peak center after a scan?#

After any scan the peaks object is updated with statistics from the last scan:

peaks.cen    # center-of-mass position of the peak
peaks.com    # alias for center-of-mass
peaks.max    # position of the maximum value
peaks.min    # position of the minimum value

peaks reports results per detector signal. If more than one detector was active, index by signal name:

peaks.cen["scaler1_ch9"]    # center-of-mass for channel 9
peaks.max["scaler1_ch9"]    # position of maximum for channel 9

Move a motor to the peak center:

%mov tabx peaks.cen["scaler1_ch9"]

How do I get help on a scan plan or function?#

In IPython, append ? to any function name to see its docstring, or ?? to see its full source code:

lup?          # show the lup() docstring (arguments, description, examples)
ascan?        # show the ascan() docstring
grid_scan?    # show grid_scan() help
counters?     # show the counters object docstring

lup??         # show lup() full source code

To see all plans and functions currently in the session namespace:

%whos         # list all variables, their types and sizes

To list available scan plans specifically, filter by type:

# Plans are generator functions — search by name pattern
[k for k in dir() if "scan" in k]

To explore devices available for loading:

find_loadable_devices()              # all devices in devices.yml
find_loadable_devices(label="4idg")  # filter by label
find_loadable_devices(name="kb")     # substring match on name