f

Author: wakonig

docs/learn/scans/argument-bundles.md

@@ -0,0 +1,88 @@
+---
+related:
+  - title: ScanArgument
+    url: learn/scans/scanargument.md
+  - title: GUI Config
+    url: learn/scans/gui-config.md
+  - title: Learn by Example
+    url: learn/scans/learn-by-example.md
+---
+
+# Argument Bundles
+
+This page explains how scans can describe repeated positional input bundles when a normal fixed
+Python signature is not enough.
+
+## The Scan Signature
+
+In the current scan implementation, a scan definition is described largely by its `__init__`
+signature plus a few class attributes.
+
+The scan server serializes that signature and publishes it to clients. The client then uses it to:
+
+- expose the scan under `scans.<name>`
+- attach a live Python signature in IPython
+- validate kwargs and bundled positional inputs
+- resolve device-name strings to device objects when the annotations require that
+
+This means the signature is no longer only local Python documentation. It is part of the runtime API
+contract between the scan server, the client, and GUIs.
+
+## `arg_input` and `arg_bundle_size`
+
+!!! tip
+    `arg_input` and `arg_bundle_size` are special cases for scans with an undefined number of
+    input arguments. Most scans developed in plugins do not need them.
+
+If the number of input arguments is not fixed, the usual Python-style fixed signature is not enough.
+
+For example, a line scan can work with any number of motors in parallel, so the scan cannot rely on
+one fixed positional argument layout in the way an ordinary Python function usually would.
+
+In those cases, scans with repeated positional bundles declare those bundles explicitly.
+
+For a line scan, that can look like this:
+
+```py
+arg_input = {
+    "device": DeviceBase,
+    "start": float,
+    "stop": float,
+}
+arg_bundle_size = {"bundle": 3, "min": 1, "max": None}
+```
+
+`arg_bundle_size` then tells BEC how many positional values belong to one bundle and how many
+bundles are allowed.
+
+This is what lets BEC validate a call such as:
+
+```py
+scans.line_scan(dev.samx, -1, 1, dev.samy, -2, 2, steps=5, relative=False)
+```
+
+without treating those positional arguments as an unstructured `*args` blob.
+
+Rich input metadata for individual parameters is covered separately on
+[ScanArgument](scanargument.md).
+
+## Reloading The Scan Server
+
+If you add a new scan or change an existing scan class, the scan server must reload that Python code
+before the changes become available.
+
+In practice, that means you should restart or reload the scan server after editing scan
+implementations. Otherwise the running server will continue using the old version of the scan.
+
+## Next Step
+
+After argument bundles, continue with [GUI Config](gui-config.md) to see how scans group inputs for
+graphical clients.
+
+## What To Remember
+
+!!! info "What to remember"
+    - The serialized scan signature is part of the runtime API between the scan server, clients, and GUIs.
+    - `arg_input` and `arg_bundle_size` define repeated positional bundles such as move targets or line-scan ranges.
+    - `ScanArgument` covers rich metadata for individual inputs, while argument bundles describe repeated positional structure.
+    - After changing scan code, the scan server must be reloaded or restarted.

docs/learn/scans/gui-config.md

@@ -0,0 +1,78 @@
+---
+related:
+  - title: ScanArgument
+    url: learn/scans/scanargument.md
+  - title: Argument Bundles
+    url: learn/scans/argument-bundles.md
+  - title: Learn by Example
+    url: learn/scans/learn-by-example.md
+---
+
+# GUI Config
+
+This page explains how scans can group their inputs for graphical clients through `gui_config`.
+
+## What `gui_config` Does
+
+`gui_config` describes how scan inputs should be grouped in graphical interfaces.
+
+For example, a scan can group inputs under headings such as:
+
+- `Device`
+- `Movement Parameters`
+- `Acquisition Parameters`
+
+This does not change how the scan runs. It helps GUIs present scan inputs in a clear structure
+instead of showing one flat list of parameters.
+
+## A Typical Example
+
+```py
+gui_config = {
+    "Device 1": ["motor1", "start_motor1", "stop_motor1"],
+    "Device 2": ["motor2", "start_motor2", "stop_motor2"],
+    "Movement Parameters": ["step", "relative"],
+    "Acquisition Parameters": [
+        "exp_time",
+        "frames_per_trigger",
+        "settling_time",
+        "readout_time",
+    ],
+}
+```
+
+In this example, the scan definition is still the same Python class and the same Python signature.
+`gui_config` only changes how that information is grouped and presented in graphical clients.
+
+## How It Fits With Scan Signatures
+
+`gui_config` does not replace the scan signature or `ScanArgument` metadata.
+
+Instead, these pieces work together:
+
+- the signature defines which inputs exist
+- `ScanArgument` enriches individual inputs with labels, units, bounds, and descriptions
+- `gui_config` groups those inputs into a clearer layout for GUIs
+
+This is why `gui_config` is best thought of as presentation metadata rather than execution logic.
+
+## Reloading The Scan Server
+
+If you add a new scan or change an existing scan class, the scan server must reload that Python code
+before the changes become available.
+
+In practice, that means you should restart or reload the scan server after editing scan
+implementations. Otherwise the running server will continue using the old version of the scan.
+
+## Next Step
+
+If you want to see `gui_config` and related scan-definition details in a richer real scan, read the
+[worked example: hexagonal scan](hexagonal-scan-example.md).
+
+## What To Remember
+
+!!! info "What to remember"
+    - `gui_config` groups scan inputs for graphical clients.
+    - It changes presentation, not scan execution.
+    - `gui_config` works alongside the scan signature and `ScanArgument` metadata.
+    - After changing scan code, the scan server must be reloaded or restarted.

docs/learn/scans/learn-by-example.md

@@ -12,8 +12,8 @@ related:
     url: learn/scans/scan-info.md
   - title: ScanArgument
     url: learn/scans/scanargument.md
-  - title: Scan Definition Info
-    url: learn/scans/scan-definition-info.md
+  - title: GUI Config
+    url: learn/scans/gui-config.md
 ---
 
 # Learn by Example

docs/learn/scans/motions.md

@@ -0,0 +1,69 @@
+---
+related:
+  - title: Scan Lifecycle
+    url: learn/scans/lifecycle.md
+  - title: Scan Components
+    url: learn/scans/scan-components.md
+  - title: Argument Bundles
+    url: learn/scans/argument-bundles.md
+---
+
+# Motions
+
+In BEC, a scan does not have to acquire detector data.
+
+A coordinated motion can also be treated as a scan if it uses the same lifecycle, reporting model,
+and request interface as other scans. That is why commands such as `mv` and `umv` are implemented
+with the same scan framework even though their main job is to reposition motors.
+
+This allows motion-only commands to benefit from the scan infrastructure:
+
+- it can reuse the same argument handling and validation
+- it can publish status in the same general format
+- it can use the same actions and components helpers
+- it can fit naturally into the same client and server model as other scan-like operations
+
+## Marking A Motion-Only Command
+
+There are two flags that a scan can set to indicate that it is not a data-taking scan:
+- `is_scan=False` indicates that the operation is not a scan, so it should be kept separate from ordinary scan entries in user interfaces.
+- `scan_type=None` indicates that the operation is neither hardware-triggered nor software-triggered, so it should not be confused with acquisition scans.
+
+## `move` and `updated_move`
+
+Both `move` and `updated_move` are motion commands implemented through the scan interface.
+
+They accept repeated motor/target bundles, support relative motion, and run through the same hook
+structure as other scans.
+
+They are exposed as `scans.mv` and `scans.umv` or through the high-level-interface as 
+
+- `umv` for `scans.umv(..., relative=False)`
+- `umvr` for `scans.umv(..., relative=True)`
+- `mv` for `scans.mv(..., relative=False)`
+- `mvr` for `scans.mv(..., relative=True)`
+
+## The Shared Lifecycle
+
+Even though this command is motion-only, it still defines the same lifecycle hooks:
+
+- `prepare_scan`
+- `open_scan`
+- `stage`
+- `pre_scan`
+- `scan_core`
+- `post_scan`
+- `unstage`
+- `close_scan`
+- `on_exception`
+
+In motion-only scans, most lifecycle hooks are kept empty or very simple. In particular, `scan_core` is the main place where the motion logic lives.
+
+## What To Remember
+
+!!! info "What to remember"
+    - In BEC, a scan does not have to acquire data to use the scan framework.
+    - Coordinated motions such as `move` and `updated_move` can use the same lifecycle and reporting model as scans.
+    - Motion-only commands can still reuse argument bundles, actions, components, and scan status reporting.
+    - To mark a motion-only command, set `is_scan=False` and `scan_type=None` in the scan class.
+    - Lifecycle hooks must be defined, but they can be kept simple or empty if they are not needed.