Skip to content

scanargument.md

Latest commit

 

History

History
148 lines (114 loc) · 4.76 KB

scanargument.md

File metadata and controls

148 lines (114 loc) · 4.76 KB
related
title url
Position Generators
learn/scans/position-generators.md
title url
Argument Bundles
learn/scans/argument-bundles.md
title url
GUI Config
learn/scans/gui-config.md
title url
Learn by Example
learn/scans/learn-by-example.md

ScanArgument

ScanArgument(...) enables a scan to attach rich metadata to one of its inputs.

As a result, the signature can provide more information to users and clients, such as which units an input uses, which bounds apply, and how the input should be labeled in a GUI.

!!! Warning "It is highly recommended to use ScanArgument for any scan input."

A Typical Example

from typing import Annotated

from bec_lib.scan_args import ScanArgument, Units


exp_time: Annotated[
    float,
    ScanArgument(display_name="Exposure Time", units=Units.s, ge=0),
] = 0

This says several things at once:

  • the input should be treated as a float
  • GUIs should label it as Exposure Time
  • the value is expressed in seconds
  • the value must be greater than or equal to zero

Reusing Common Annotations With DefaultArgType

Writing out full Annotated[..., ScanArgument(...)] definitions is useful when a scan needs a custom input definition. However, BEC already provides shared aliases for the common internal scan parameters that are represented in scan info{data-preview} and used in many scans.

To avoid repeating those annotations in every scan class, these common definitions are collected in DefaultArgType.

For example, the typical example above is equivalent to:

from bec_lib.scan_args import DefaultArgType


exp_time: DefaultArgType.ExposureTime = 0

The same pattern is used for other internal scan parameters such as FramesPerTrigger, SettlingTime, SettlingTimeAfterTrigger, ReadoutTime, BurstAtEachPoint, and also for common boolean scan options such as Relative.

This keeps scan signatures shorter while still preserving the same ScanArgument metadata for validation, GUI generation, and scan discovery.

Common ScanArgument Fields

Some of the most commonly used fields are listed below.

Field Role Typical use
display_name Provides a clearer user-facing label than the raw Python parameter name. GUI labels
description Provides a longer explanation of what the input means. help text or documentation
tooltip Adds short explanatory text for interactive UIs. GUI hover text
units Declares the explicit unit for the input, such as seconds or degrees. user-facing display
reference_units Tells BEC to interpret the value in the units of another input, such as a motor argument. user-facing display
gt, ge, lt, le Applies numeric bounds to the input. validation

Units and Reference Units

Two patterns are especially common.

Explicit units:

  • Annotated[float, ScanArgument(units=Units.s)]
  • Annotated[float, ScanArgument(units=Units.eV)]
  • Annotated[float, ScanArgument(units=Units.deg)]

Reference units:

  • Annotated[float, ScanArgument(reference_units="motor1")]
  • Annotated[float, ScanArgument(reference_units="motor2")]
  • Annotated[float, ScanArgument(reference_units="device")]

Reference units are especially useful for scan inputs such as start, stop, or step size, where the value should automatically use the same unit as a related device input.

Next Step

After ScanArgument, continue with argument bundles{data-preview} for repeated positional inputs and GUI config{data-preview} for graphical grouping.

What To Remember

!!! info "What to remember" - ScanArgument attaches rich metadata to individual scan inputs. - It is usually used through Annotated[..., ScanArgument(...)]. - It helps BEC validate inputs and present them clearly in GUIs and clients.