| related |
|
|---|
A scan must keep track of its runtime metadata and parameters in a structured way. In BEC, that is the role of the ScanInfo model. Every scan has an instance of ScanInfo that is created by ScanBase when the scan object is initialized and then updated by the concrete scan during its lifecycle. It is accessible as self.scan_info from any scan hook or method, although it is most commonly updated through a helper method called update_scan_info(...) that can update both known top-level fields and extra scan-specific parameters in one call.
Without one shared runtime model, each part of BEC would need to reconstruct the scan from a mix of request arguments, device instructions, and status messages.
scan_info solves that by keeping the scan description in one structured object, including:
- what scan is running
- how many points or monitored readouts it expects
- which timing parameters apply
- which devices should be reported
- which request inputs the user originally sent
- which extra scan-specific parameters should travel with the scan
The ScanInfo model is the single source of truth for the scan's runtime metadata and is the main content for published scan status messages. Any device or client that needs to know about the scan relies on it for the most accurate and up-to-date description.
The current ScanInfo model contains the following fields.
| Field | Role | Typically set by |
|---|---|---|
scan_name |
Name of the scan class published to the client, for example acquire. |
ScanBase from the class attribute |
scan_id |
Unique runtime identifier for this scan instance. | Queue and worker setup |
scan_type |
Internal scan type, currently software_triggered or hardware_triggered. |
ScanBase from the class attribute |
scan_number |
Assigned scan number for the run, if available. | Queue and runtime bookkeeping |
dataset_number |
Assigned dataset number for the run, if available. | Queue and runtime bookkeeping |
num_points |
Number of logical scan points. | Usually prepare_scan |
positions |
Prepared position array for scans that precompute positions. | Usually prepare_scan |
exp_time |
Exposure time for the scan. | __init__ or update_scan_info(...) |
frames_per_trigger |
Number of frames collected per trigger. | __init__ or update_scan_info(...) |
settling_time |
Settling delay before a software trigger. | __init__ or update_scan_info(...) |
settling_time_after_trigger |
Settling delay after a software trigger. | __init__ or update_scan_info(...) |
readout_time |
Readout delay after triggering. | __init__ or update_scan_info(...) |
burst_at_each_point |
How many bursts are collected at each point. | __init__ or update_scan_info(...) |
relative |
Whether prepared positions are interpreted relative to the current device state. | __init__ or update_scan_info(...) |
run_on_exception_hook |
Whether the scan should run its on_exception cleanup hook on interruption. |
Base initialization or later update |
request_inputs |
Structured copy of the original request inputs sent by the client. | ScanBase initialization |
readout_priority_modification |
Requested overrides to device readout priority during the scan. | Usually helper calls in actions |
scan_report_instructions |
UI/report instructions such as progress widgets or readback displays. | Usually helper calls in actions |
scan_report_devices |
Devices highlighted in scan reports. Device objects are stored by name. | Usually update_scan_info(...) |
monitor_sync |
Monitor synchronization mode for fly scans. This field is marked for removal. | Scan-specific logic when needed |
additional_scan_parameters |
Extra scan-specific parameters that do not have dedicated top-level fields. | Unknown keys passed to update_scan_info(...) |
user_metadata |
User-provided metadata attached to the request. | Request setup |
system_config |
System-side configuration relevant to the scan, such as file-writing settings. | Request setup |
scan_queue |
Name of the queue this scan belongs to. | Request setup |
metadata |
Additional runtime metadata associated with the scan request. | Request setup and runtime bookkeeping |
num_monitored_readouts |
Total number of monitored readouts expected for the run. | Usually prepare_scan |
After scan_info, continue with scan actions{data-preview}.
That page covers the high-level scan operations used to publish scan state and coordinate device work. After that, move on to scan components{data-preview} for the reusable scan patterns built on top of those operations.
!!! info "What to remember"
- scan_info is the shared runtime metadata model for a scan.
- ScanBase creates it, and concrete scans usually finish populating it during prepare_scan.
- Known updates go to named ScanInfo fields; unknown updates go to additional_scan_parameters.
- Published scan status messages are derived from scan_info.