Skip to content

Run your first scan

Goal

Discover a scan, run it with a simulated motor, and keep the report that identifies your measurement.

Before you start

Continue in the BEC IPython session from Move a device, with the demo configuration loaded and dev.samx available.

1. Discover the line scan

Type scans. and press Tab to see the scans available from your running server. For this exercise, inspect the line scan:

scans.line_scan?

This displays the scan documentation, including its signature and examples of use. For the built-in line scan, an abbreviated help display looks like this:

Signature:
scans.line_scan(
    *args,
    steps: int,
    relative: bool,
    exp_time: float = 0,
    frames_per_trigger: int = 1,
    settling_time: float = 0,
    settling_time_after_trigger: float = 0,
    readout_time: float = 0,
    burst_at_each_point: int = 1,
)
Docstring:
A line scan for one or more motors.

Args:
    *args (device: DeviceBase, start: float, stop: float): repeated scan argument bundles.
    steps (int): steps.
    relative (bool): Whether the positions are relative to the current position.
    exp_time (float [s]): Exposure time in seconds. Default: 0 s
    ...

Returns:
    ScanReport

Examples:
    Minimum:
        >>> scans.line_scan(dev.device1, -1.0, 1.0, steps=10, relative=False)
    ...

Find steps, exp_time, and relative: we will set all three explicitly below. Available scans and their defaults can differ between deployments, so use the help from your own session.

2. Run a scan and keep its report

Run a short scan over the simulated samx motor, assigning the returned report to scan_report:

scan_report = scans.line_scan(
    dev.samx, -1, 1, steps=5, exp_time=0.1, relative=False
)
Starting scan 1.
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
|seq. num|  samx  | ebpmdx |  bpm4x |  bpm5x |  bpm3x |  bpm6y | ebpmdy |  bpm4d |  bpm4s | ebpmux |
+========+========+========+========+========+========+========+========+========+========+========+
|    1   |-0.999  | 91.000 | 90.000 | 99.000 | 101.000| 108.000| 110.000| 91.000 | 101.000| 96.000 |
|    2   |-0.503  | 90.000 | 94.000 | 90.000 | 95.000 | 107.000| 106.000| 96.000 | 91.000 | 107.000|
|    3   |-0.003  | 102.000| 107.000| 108.000| 108.000| 90.000 | 109.000| 108.000| 94.000 | 103.000|
|    4   |  0.492 | 98.000 | 107.000| 106.000| 97.000 | 98.000 | 96.000 | 92.000 | 99.000 | 110.000|
|    5   |  0.997 | 110.000| 98.000 | 110.000| 95.000 | 99.000 | 92.000 | 106.000| 96.000 | 93.000 |

+========+========+========+========+========+========+========+========+========+========+========+
|  Scan 1 finished. Scan ID a1502642-4b9c-4956-ab0f-1434c0dda97c. Elapsed time: 0.70 s             |
+========+========+========+========+========+========+========+========+========+========+========+

The motor visits five equally spaced positions: -1, -0.5, 0, 0.5, and 1. relative=False makes these absolute positions, independent of the motor's starting position. exp_time=0.1 requests a 0.1-second exposure from devices that use this setting.

At each position, BEC records the monitored devices. The client shows progress and a table of their readings. Simulated readbacks can differ slightly from the requested positions, and detector values will vary between runs.

3. Identify your scan

The report belongs to this particular request. Inspect its scan ID:

scan_report.scan.scan_id

Keep scan_report in your session. You will use it to find this measurement again in Access scan data.

Next step

Continue with 05 Plot your first waveform to plot scan data, or follow Access scan data to inspect the recorded values and find the saved file. For other scan types, consult the built-in scan catalog.

What you have learned

You discovered a scan with IPython help, ran an absolute five-point measurement, and kept its report and scan ID for accessing the result.