Skip to content

Commit aeb0298

Browse files
wakonigwakonig
committed
f
1 parent 1b206a4 commit aeb0298

4 files changed

Lines changed: 251 additions & 142 deletions

File tree

‎docs/learn/scans/introduction.md‎

Lines changed: 29 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ related:
1111
# Scans in BEC
1212

1313
!!! Info "Overview"
14-
Scans are the core of BEC's functionality. They are the tools that move your devices, trigger readouts, and produce the data you analyze. In BEC, all scans follow a shared structure and report themselves in a consistent way, even when their motion logic differs.
14+
Scans are the core of BEC's functionality. They are the tools that move your devices, trigger readouts, and produce the data you analyze.
15+
16+
In BEC, all scans follow the same structure and report themselves in a consistent way, even when their motion logic differs.
1517

1618
BEC scans follow one shared model. Whether you run a simple acquisition, a line scan, a grid scan,
1719
or a continuous scan, BEC handles them in the same overall way.
@@ -39,83 +41,38 @@ For example, a line scan, a grid scan, and a continuous scan may move differentl
3941
At a high level, a scan in BEC follows this path:
4042

4143
1. The scan server publishes the available scan classes together with their serialized signatures, grouped inputs, and GUI metadata.
42-
2. The client exposes those scans dynamically, so commands such as `scans.line_scan(...)` use the current server-side definition.
43-
3. When a scan is called, the client validates the user inputs, resolves device-name strings to device objects where needed, and bundles repeated positional inputs for scans such as `line_scan` or `umv` before sending the request to the server.
44-
4. On the server, the request is queued and receives runtime identifiers.
45-
5. Once it is the scan's turn to run, the scan server queue hands over the request to a scan worker.
46-
6. The scan worker runs the scan class's lifecycle hooks and sends device instructions through Redis.
47-
7. Devices publish readouts and status updates.
48-
8. The scan bundler groups those readouts into logical scan points.
49-
9. Clients, history, and the file writer consume the resulting scan data.
50-
51-
From the user side, the important part is consistency: every scan goes through the same backend
52-
steps, reports its progress in the same general way, and produces scan data that can be accessed
53-
through the same tools afterward.
44+
1. The client exposes those scans dynamically, so commands such as `scans.line_scan(...)` use the current server-side definition.
45+
1. When a scan is called, the client sends a request to the server with the scan class's name and the provided arguments.
46+
1. On the server, the scan is assembled from the scan class and the provided arguments, and then it is put in the scan server queue.
47+
1. Once it is the scan's turn to run, the scan server queue hands over the request to a scan worker.
48+
1. The scan worker runs the scan class's lifecycle hooks.
49+
1. During the scan, the scan class may use scan actions or components to trigger readouts, move devices, or run custom logic at each scan point.
50+
1. Devices publish readouts and status updates.
51+
1. The scan bundler groups those readouts into logical scan points.
52+
1. Clients, history, and the file writer consume the resulting scan data.
53+
54+
From the user side, the important part is consistency: every scan goes through the same lifecycle
55+
steps. **If you have seen one scan, you have seen them all.** You can focus on the differences in motion logic without having to learn a new overall structure for each scan type.
5456

5557
## The Shared Scan Shape
5658

57-
As mentioned above, all BEC scans follow the same overall shape. They share the same lifecycle steps, and they use the same helpers to report themselves and produce data. This allows users to be always prompted with a familiar structure, even when the motion logic of the scan differs. The shared shape also makes it easier to learn new scans, since you can focus on the differences in motion logic rather than having to learn a new overall structure for each scan. The lifecycle steps are:
58-
59-
<!-- The table is in html as the columns would otherwise wrap. There seems to be no internal way to control column width in markdown -->
60-
<table>
61-
<colgroup>
62-
<col style="width: 24%;">
63-
<col style="width: 76%;">
64-
</colgroup>
65-
<thead>
66-
<tr>
67-
<th>Hook</th>
68-
<th>Role</th>
69-
</tr>
70-
</thead>
71-
<tbody>
72-
<tr>
73-
<td style="white-space: nowrap;"><code>prepare_scan</code></td>
74-
<td>Prepare the scan for the upcoming acquisition.</td>
75-
</tr>
76-
<tr>
77-
<td style="white-space: nowrap;"><code>open_scan</code></td>
78-
<td>Open the scan and emit a new scan status message with all relevant metadata.</td>
79-
</tr>
80-
<tr>
81-
<td style="white-space: nowrap;"><code>stage</code></td>
82-
<td>Stage the devices for the upcoming acquisition.</td>
83-
</tr>
84-
<tr>
85-
<td style="white-space: nowrap;"><code>pre_scan</code></td>
86-
<td>Run any pre-scan logic, such as preparing time-critical devices.</td>
87-
</tr>
88-
<tr>
89-
<td style="white-space: nowrap;"><code>scan_core</code></td>
90-
<td>Run the core logic of the scan; trigger readouts if needed and optionally call <code>at_each_point()</code> for per-point logic.</td>
91-
</tr>
92-
<tr>
93-
<td style="white-space: nowrap;"><code>post_scan</code></td>
94-
<td>Run any post-scan logic, such as moving devices back to their original position.</td>
95-
</tr>
96-
<tr>
97-
<td style="white-space: nowrap;"><code>unstage</code></td>
98-
<td>Unstage the devices.</td>
99-
</tr>
100-
<tr>
101-
<td style="white-space: nowrap;"><code>close_scan</code></td>
102-
<td>Close the scan and emit a final scan status message with all relevant metadata.</td>
103-
</tr>
104-
<tr>
105-
<td style="white-space: nowrap;"><code>on_exception</code></td>
106-
<td>If an exception is raised during any earlier step, run cleanup logic here.</td>
107-
</tr>
108-
</tbody>
109-
</table>
110-
111-
BEC runs these lifecycle steps in the same order every time.
112-
113-
This shared shape is why BEC scans feel related rather than like separate one-off tools.
59+
As mentioned above, all BEC scans follow the same overall shape. They use the same lifecycle and
60+
the same helpers to report themselves and produce data. That shared structure is why BEC scans feel
61+
related rather than like separate one-off tools.
62+
63+
The details of a scan may change a lot from one scan type to another, but the lifecycle around
64+
those details stays recognizable. That makes it easier to learn new scans because you can focus on
65+
the motion logic instead of relearning the full structure each time.
66+
67+
The next page, [Scan Lifecycle](lifecycle.md), breaks down those shared lifecycle steps and what
68+
each hook is responsible for.
11469

11570
## Where To Go Next
11671

11772
If you want the next layer of detail:
11873

74+
- read [Scan Lifecycle](lifecycle.md){ data-preview } to see the shared hook order used by every
75+
BEC scan.
11976
- read [Learn by example](../learn/scans/learn-by-example.md){ data-preview } to go through the `acquire` scan example in detail, and see how the shared scan shape applies to a specific scan type.
12077

12178
## What to Remember
@@ -124,5 +81,5 @@ If you want the next layer of detail:
12481
- In BEC, all scans follow the same overall shape.
12582
- Different scan types use the same backend framework, even when their motion logic differs.
12683
- Every scan reports itself in a common structured way while it runs.
127-
- Every scan has to implement the same lifecycle steps, even when some of those steps are empty.
128-
- The lifecycle steps are called in the same order for every scan.
84+
- Every scan follows the same lifecycle, even when some hooks do very little.
85+
- The lifecycle order is fixed, which makes new scan types easier to understand.

0 commit comments

Comments
 (0)